automatica11y 0.3.3 → 0.4.0

package/src/harness/generate/wc-recipes.js

@@ -0,0 +1,132 @@
+/**
+ * Candidate web component fixtures, built from what the element says about itself once it's defined:
+ * the attributes it observes, the members its class has, and the slots its shadow root offers.
+ * A candidate is a guess until the probe has seen it behave (see probe.js). None of this names a library.
+ */
+import { markingSource } from "./marking.js";
+import { ATTEMPT_LIMIT, GENERATABLE } from "./shared.js";
+
+/** The module around every candidate: the marking code and a mount function that starts it. */
+function frame(archetype, body) {
+  return `${markingSource(archetype)}
+export default function mount(container) {
+${body.split("\n").map((line) => (line ? `  ${line}` : line)).join("\n")}
+  startMarking();
+}
+`;
+}
+
+const has = (facts, name) => facts.attributes.includes(name) || facts.members.includes(name);
+const slotFor = (facts, pattern) => facts.slots.find((name) => pattern.test(name));
+
+// ---- dialog ----
+
+/** The ways a dialog element is commonly opened, from what it has. */
+function openers(facts) {
+  const found = [];
+  if (facts.attributes.includes("open")) found.push(["attribute", `dialog.setAttribute("open", "");`]);
+  if (facts.members.includes("open")) found.push(["property", "dialog.open = true;"]);
+  if (facts.members.includes("showModal")) found.push(["showModal()", "dialog.showModal();"]);
+  if (facts.members.includes("show")) found.push(["show()", "dialog.show();"]);
+  return found;
+}
+
+function dialogs(tagName, facts) {
+  const titleSlot = slotFor(facts, /title|header|heading/i);
+  const heading = titleSlot ? `<h2 slot="${titleSlot}">Edit profile</h2>` : "<h2>Edit profile</h2>";
+  return openers(facts).map(([how, code]) => ({
+    id: `dialog-${how.replace(/[^a-z]+/gi, "-").replace(/-$/, "")}`,
+    summary: `a ${tagName} opened with its ${how}`,
+    source: frame("dialog", `container.innerHTML = \`<button type="button" data-a11y-trigger>Open dialog</button><${tagName}>${heading}<p>Update your details.</p><button type="button">Close</button></${tagName}>\`;
+const dialog = container.querySelector(${JSON.stringify(tagName)});
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => {
+  ${code}
+});`),
+    used: [tagName],
+  }));
+}
+
+// ---- tooltip ----
+
+function tooltips(tagName, facts) {
+  return facts.attributes.filter((name) => /^(tip|tooltip|content|text|label|title|message|description)$/.test(name)).map((name) => ({
+    id: `tooltip-${name}`,
+    summary: `a ${tagName} that takes its text from ${name}`,
+    source: frame("tooltip", `container.innerHTML = \`<${tagName} ${name}="Saves your work."><button type="button" data-a11y-trigger>Save</button></${tagName}>\`;`),
+    used: [tagName],
+  }));
+}
+
+// ---- live region ----
+
+function messages(tagName, facts) {
+  const list = [{
+    id: "message-appended",
+    summary: `a ${tagName} added to the page when the trigger is pressed`,
+    source: frame("live-region", `container.innerHTML = \`<button type="button" data-a11y-trigger>Show message</button><div id="slot"></div>\`;
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => {
+  const message = document.createElement(${JSON.stringify(tagName)});
+  message.textContent = "Saved.";
+  container.querySelector("#slot").append(message);
+});`),
+    used: [tagName],
+  }];
+  if (has(facts, "open")) {
+    list.push({
+      id: "message-open",
+      summary: `a ${tagName} shown by setting open`,
+      source: frame("live-region", `container.innerHTML = \`<button type="button" data-a11y-trigger>Show message</button><${tagName}>Saved.</${tagName}>\`;
+const message = container.querySelector(${JSON.stringify(tagName)});
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => message.setAttribute("open", ""));`),
+      used: [tagName],
+    });
+  }
+  return list;
+}
+
+// ---- form field ----
+
+/** The element isn't marked as the trigger here. The marking code finds the input inside its shadow root, which is the thing a person types in. */
+function fields(tagName, facts) {
+  if (!["value", "name", "label", "placeholder", "checked", "type"].some((name) => has(facts, name))) return [];
+  const list = [{
+    id: "field-wrapped-label",
+    summary: `a ${tagName} inside a wrapping label`,
+    source: frame("form-field", `container.innerHTML = \`<label>Name <${tagName}></${tagName}></label>\`;`),
+    used: [tagName],
+  }];
+  if (has(facts, "label")) {
+    list.push({
+      id: "field-label-attribute",
+      summary: `a ${tagName} with a label attribute`,
+      source: frame("form-field", `container.innerHTML = \`<${tagName} label="Name"></${tagName}>\`;`),
+      used: [tagName],
+    });
+  }
+  return list;
+}
+
+/**
+ * Candidates for one element and archetype. Archetypes with no recipe here (menu, tabs, accordion, combobox) return none,
+ * because those depend on child elements and slots that an element can't describe well enough to guess.
+ * @param {{ archetype: string, tag: string, facts: { attributes: string[], members: string[], slots: string[] } }} input
+ */
+export function wcCandidates({ archetype, tag, facts }) {
+  const build = { dialog: dialogs, tooltip: tooltips, "live-region": messages, "form-field": fields }[archetype];
+  return build ? build(tag, facts) : [];
+}
+
+/**
+ * Candidates for a web component package, from what the element the mapping found says about itself.
+ * @param {{ archetype: string, entry: { tag?: string }, facts: Record<string, { attributes: string[], members: string[], slots: string[] }> }} input
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateWc({ archetype, entry, facts }) {
+  if (!GENERATABLE.has(archetype)) return { candidates: [], reason: `Nothing is generated for the ${archetype} archetype.` };
+  const tag = entry.tag;
+  if (!tag || !facts[tag]) return { candidates: [], reason: "No custom element looks like this archetype, so there's nothing to build a fixture around." };
+  const candidates = wcCandidates({ archetype, tag, facts: facts[tag] }).slice(0, ATTEMPT_LIMIT);
+  return candidates.length
+    ? { candidates, reason: null }
+    : { candidates: [], reason: `${tag} doesn't show a way to wire a ${archetype} (for example, an open attribute or a tip attribute), and no recipe covers a web component ${archetype} without one.` };
+}

package/src/harness/npm-install.js

@@ -33,9 +33,9 @@ export function installedVersion(dir, name) {
 
 /**
  * Install a package into its own directory, never next to another target's install.
- * npm adds the peer dependencies. A React package also needs react-dom, so add it when the peers left it out.
+ * npm adds the peer dependencies. A React package also needs react-dom, and a Vue package needs vue, so add them when the peers left them out.
  * Install scripts stay off, because the code is untrusted until it runs in the browser sandbox.
- * @param {{ dir: string, name: string, version: string, flavor: "react" | "wc" | "unknown", run?: typeof runNpm }} options
+ * @param {{ dir: string, name: string, version: string, flavor: "react" | "vue" | "wc" | "unknown", run?: typeof runNpm }} options
  */
 export async function installPackage({ dir, name, version, flavor, run = runNpm }) {
   mkdirSync(dir, { recursive: true });
@@ -69,15 +69,46 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
       await npm(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"]);
       warnings.push(`${name} didn't bring in react, so the latest react and react-dom were added.`);
     } else if (!installedVersion(dir, "react-dom")) {
-      await npm(["install", `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
+      // Name react too. A loose install prunes a package that only arrived as a peer, and react did.
+      await npm(["install", `react@${react}`, `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
     }
   }
-  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), version: installedVersion(dir, name) };
+  if (flavor === "vue" && !installedVersion(dir, "vue")) {
+    await npm(["install", "vue", ...NPM_FLAGS, "--legacy-peer-deps"]);
+    warnings.push(`${name} didn't bring in vue, so the latest vue was added.`);
+  }
+  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), vue: installedVersion(dir, "vue"), version: installedVersion(dir, name) };
+}
+
+/** The installed framework runtimes (React, React DOM, Vue), named again so a loose install can't prune them. */
+function pinnedRuntime(dir) {
+  return ["react", "react-dom", "vue"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+}
+
+const PACKAGE_SPEC = /^(@[a-z0-9~][\w.~-]*\/)?[a-z0-9~][\w.~-]*(@[\w.^~<>=*|-]+)?$/i;
+
+/**
+ * Install packages a mapping names beside the target: a token stylesheet, a theme, or another package the library's own
+ * documentation says to load. Only plain package specs are accepted (no flags, paths, or URLs). Install scripts stay off.
+ * @param {{ dir: string, specs: string[], run?: typeof runNpm }} options
+ * @returns {Promise<{ installed: string[], warnings: string[] }>}
+ */
+export async function installExtraPackages({ dir, specs, run = runNpm }) {
+  const wanted = [...new Set(specs)];
+  if (wanted.length === 0) return { installed: [], warnings: [] };
+  for (const spec of wanted) if (!PACKAGE_SPEC.test(spec)) throw new Error(`The mapping's install list has "${spec}", which isn't a package name with an optional version.`);
+  try {
+    await run(["install", ...wanted, ...pinnedRuntime(dir), "--legacy-peer-deps", ...NPM_FLAGS], dir);
+  } catch (error) {
+    throw new Error(`npm couldn't install ${wanted.join(", ")}: ${firstLine(error.message)}`);
+  }
+  return { installed: wanted, warnings: [`The mapping named ${wanted.join(", ")} to install beside the library, so it was installed.`] };
 }
 
 /**
  * Find the optional peer dependencies that installed packages declare, with the range each asks for.
- * npm leaves these out, but a library's default setup can still need one (MUI needs an Emotion package).
+ * npm leaves these out, but a library's default setup can still need one
+ * (e.g., React libraries may need an Emotion package).
  * @param {string} dir The install folder.
  * @returns {Map<string, string>} Package name to range.
  */
@@ -113,8 +144,8 @@ export async function installOptionalPeers({ dir, unresolved, run = runNpm }) {
   const declared = declaredOptionalPeers(dir);
   const wanted = unresolved.filter((name) => declared.has(name) && !installedVersion(dir, name));
   if (wanted.length === 0) return { installed: [], warnings: [] };
-  // A loose install prunes packages that only arrived as peers, so name React again to keep it.
-  const keep = ["react", "react-dom"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+  // A loose install prunes packages that only arrived as peers, so name the framework again to keep it.
+  const keep = pinnedRuntime(dir);
   const specs = [...wanted.map((name) => `${name}@${declared.get(name)}`), ...keep];
   try {
     await run(["install", ...specs, "--legacy-peer-deps", ...NPM_FLAGS], dir);

package/src/harness/settle.js

@@ -0,0 +1,17 @@
+/**
+ * Wait for fades and slides to finish before a state is scanned, so contrast is measured on the settled colors and not on a
+ * half-transparent element mid-transition. Animations that never end (a spinner) are left alone. Waits at most 2 seconds.
+ * @param {import("playwright-core").Page} page
+ */
+export async function settleAnimations(page) {
+  await page.evaluate(async () => {
+    const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    await frame();
+    const finite = () => document.getAnimations().filter((a) => a.effect && a.effect.getComputedTiming().endTime !== Infinity);
+    const deadline = Date.now() + 2000;
+    while (finite().length > 0 && Date.now() < deadline) {
+      await Promise.race([Promise.allSettled(finite().map((a) => a.finished)), new Promise((done) => setTimeout(done, 200))]);
+      await frame();
+    }
+  });
+}

package/src/harness/storybook.js

@@ -12,6 +12,7 @@ export const ARCHETYPE_PATTERNS = {
   "form-field": /\binputs?\b|\btext ?(field|area|box)\b|\bform\b|\bcheckbox(es)?\b|\bradio\b|\bswitch\b|\bfield\b/i,
   accordion: /\baccordions?\b|\bcollaps(e|ible)\b|\bdisclosure\b/i,
   tooltip: /\btooltips?\b|\bpopovers?\b/i,
+  "live-region": /\balerts?\b(?! ?dialogs?)|\bstatus\b|\btoasts?\b|\bsnackbars?\b|\bnotifications?\b|\blive ?regions?\b/i,
   chart: /\bcharts?\b|\bgraphs?\b|\bplots?\b/i,
 };
 

package/src/harness/url.js

@@ -8,12 +8,12 @@ const NETWORK_IDLE_MS = 30_000;
  * The returned `warnings` hold anything the report should mention, such as a network that never went idle.
  * @param {import("playwright-core").Browser} browser
  * @param {string} url
- * @param {{ viewport?: { width: number, height: number }, forcedColors?: boolean, beforeGoto?: (page: import("playwright-core").Page) => void | Promise<unknown>, waitUntil?: "load" | "networkidle" }} [options]
+ * @param {{ viewport?: { width: number, height: number }, forcedColors?: boolean, colorScheme?: "light" | "dark", reducedMotion?: boolean, contrast?: "more" | "less", reducedTransparency?: boolean, beforeGoto?: (page: import("playwright-core").Page) => void | Promise<unknown>, waitUntil?: "load" | "networkidle" }} [options]
  *   `beforeGoto` runs before navigation, so a caller can attach console listeners that see the first messages.
  *   `waitUntil` defaults to `networkidle`. Local fixture pages don't need to wait for the network.
  */
-export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors = false, beforeGoto, waitUntil = "networkidle" } = {}) {
-  const context = await browser.newContext({ viewport, deviceScaleFactor: 1, forcedColors: forcedColors ? "active" : "none" });
+export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors = false, colorScheme = "light", reducedMotion = false, contrast, reducedTransparency = false, beforeGoto, waitUntil = "networkidle" } = {}) {
+  const context = await browser.newContext({ viewport, deviceScaleFactor: 1, forcedColors: forcedColors ? "active" : "none", colorScheme, reducedMotion: reducedMotion ? "reduce" : "no-preference" });
   await context.addInitScript(recordClosedShadowRoots);
   await context.addInitScript(recordCustomElements);
   /** @type {string[]} */
@@ -21,6 +21,16 @@ export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors
   try {
     const page = await context.newPage();
     page.setDefaultTimeout(30_000);
+    // Playwright can't set prefers-reduced-transparency or prefers-contrast: less, so ask the browser directly.
+    // A page opened this way sets nothing else, because the call replaces any other emulated media features.
+    const features = [
+      ...(contrast ? [{ name: "prefers-contrast", value: contrast }] : []),
+      ...(reducedTransparency ? [{ name: "prefers-reduced-transparency", value: "reduce" }] : []),
+    ];
+    if (features.length) {
+      const session = await context.newCDPSession(page);
+      await session.send("Emulation.setEmulatedMedia", { features });
+    }
     await beforeGoto?.(page);
     let response;
     try {

package/src/plan/classify.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cleanSubpath } from "./subpath.js";
 
 /**
  * @typedef {"npm" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
@@ -22,7 +23,7 @@ import { fileURLToPath } from "node:url";
 const LOCAL_PATH = /^(\.{1,2}(\/|$)|\/|~(\/|$)|file:)/;
 const LABEL = /^([A-Za-z0-9][\w.-]*)=(.+)$/;
 const HTTP_URL = /^https?:\/\//i;
-const NPM_NAME = /^(?:@([a-z0-9][a-z0-9._~-]*)\/)?([a-z0-9][a-z0-9._~-]*)(?:@(.*))?$/;
+const NPM_NAME = /^(?:@([a-z0-9][a-z0-9._~-]*)\/)?([a-z0-9][a-z0-9._~-]*)(?:@([^/]*))?(?:\/(.+))?$/;
 const COMPONENT_SOURCE = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".vue", ".svelte"]);
 
 /**
@@ -129,17 +130,23 @@ function classifyNpm(spec, base) {
     if (/[A-Z]/.test(spec) && NPM_NAME.test(spec.toLowerCase())) return failed(`"${spec}" isn't a valid package name. npm package names are lowercase.`, base);
     return failed(`"${spec}" isn't a valid npm package name. Write npm:name, npm:@scope/name, or npm:name@version.`, base);
   }
-  const [, scope, name, version] = match;
+  const [, scope, name, version, rawSubpath] = match;
   if (version === "") return failed(`"${spec}" ends with @ but has no version.`, base);
+  let subpath = null;
+  if (rawSubpath !== undefined) {
+    const cleaned = cleanSubpath(rawSubpath);
+    if ("reason" in cleaned) return failed(`"${spec}" isn't a valid sub-path: ${cleaned.reason}. Write npm:name/sub/path or npm:name@version/sub/path.`, base);
+    subpath = /** @type {{ subpath: string }} */ (cleaned).subpath;
+  }
   const full = scope ? `@${scope}/${name}` : name;
   return {
     ...base,
-    name: base.name || full,
+    name: base.name || (subpath ? `${full}/${subpath}` : full),
     status: "ok",
     reason: null,
     kind: "npm",
     evidenceLevel: "component",
-    resolved: { name: full, requested: version ?? null, version: null },
+    resolved: { name: full, requested: version ?? null, version: null, subpath },
   };
 }
 

package/src/plan/mapping.js

@@ -14,6 +14,7 @@ const BASE_NAMES = {
   "form-field": ["input", "textfield", "textinput", "field", "checkbox"],
   accordion: ["accordion", "collapsible", "disclosure"],
   tooltip: ["tooltip", "popover"],
+  "live-region": ["alert", "status", "toast", "snackbar", "notification", "liveregion"],
   chart: ["chart", "linechart", "barchart"],
 };
 
@@ -24,21 +25,23 @@ export const TEMPLATED = new Set(["button", "link"]);
 const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
 
 /** How well a name fits an archetype. 0 means it doesn't. */
-function score(archetype, name) {
+export function score(archetype, name) {
   if (!ARCHETYPE_PATTERNS[archetype].test(words(name))) return 0;
   const compact = name.replace(/[-_\s]/g, "").toLowerCase();
   const last = words(name).toLowerCase().split(" ").pop();
   const bases = BASE_NAMES[archetype];
-  if (bases.includes(compact)) return 4;
-  if (bases.includes(last)) return 3;
-  if (bases.some((base) => compact.startsWith(base))) return 2;
+  // Names listed first are closer to the archetype itself, so `tooltip` beats `popover` when both are there.
+  if (bases.includes(compact)) return 4 - bases.indexOf(compact) * 0.1;
+  if (bases.includes(last)) return 3 - bases.indexOf(last) * 0.1;
+  const starts = bases.findIndex((base) => compact.startsWith(base));
+  if (starts !== -1) return 2 - starts * 0.1;
   return 1;
 }
 
 /**
- * Guess which exports (React) or tags (web components) stand for each archetype.
+ * Guess which exports (React or Vue) or tags (web components) stand for each archetype.
  * The result is a starting point. A person or the skill checks it before trusting it.
- * @param {{ flavor: "react" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
+ * @param {{ flavor: "react" | "vue" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
  * @returns {Record<string, any>}
  */
 export function candidateMapping({ flavor, exports = [], tags = [] }) {
@@ -59,7 +62,7 @@ export function candidateMapping({ flavor, exports = [], tags = [] }) {
     const parts = info?.parts ?? [];
     // Flat compound libraries (DialogRoot, DialogTrigger, DialogContent) have sibling exports that share a prefix.
     // A button or link usually sits beside ButtonBase, ButtonGroup, and the like, which aren't its parts, so only real parts (Button.Root) count there.
-    const siblings = flavor === "react" && !TEMPLATED.has(archetype) ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
+    const siblings = flavor !== "wc" && !TEMPLATED.has(archetype) ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
     const compound = parts.length > 0 || siblings.length >= 2;
     const templated = TEMPLATED.has(archetype) && !compound;
     mapping[archetype] = {

package/src/plan/resolve-npm.js

@@ -1,8 +1,9 @@
 import { execFile } from "node:child_process";
+import { ADAPTERS } from "../frameworks/index.js";
+import { checkExports, notExportedMessage } from "./subpath.js";
 
-const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated"];
+const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports"];
 const OTHER_FRAMEWORKS = {
-  vue: "Vue",
   "@angular/core": "Angular",
   svelte: "Svelte",
   "solid-js": "Solid",
@@ -44,19 +45,19 @@ export function npmView(spec, { timeoutMs = 60_000 } = {}) {
 }
 
 /**
- * Guess how a package renders from its metadata alone. React wins when both signals appear.
+ * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue.
  * `npm` means the metadata can't say, so the run decides after it installs and loads the package.
  * @param {any} meta
- * @returns {{ kind: "npm-react" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
+ * @returns {{ kind: "npm-react" | "npm-vue" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
  */
 export function detectFlavor(meta) {
   const peers = meta.peerDependencies ?? {};
   const deps = meta.dependencies ?? {};
-  if ("react" in peers || "react-dom" in peers || "react" in deps) {
-    const how = "react" in peers || "react-dom" in peers ? "peer dependency" : "dependency";
-    return { kind: "npm-react", framework: "React", reason: `The package lists react as a ${how}.` };
-  }
+  const react = /** @type {any} */ (ADAPTERS.react.detect(meta));
+  if (react) return react;
   if (meta.customElements) return { kind: "npm-wc", framework: "Web components", reason: "The package has a customElements manifest." };
+  const vue = /** @type {any} */ (ADAPTERS.vue.detect(meta));
+  if (vue) return vue;
   for (const [name, label] of Object.entries(OTHER_FRAMEWORKS)) {
     if (name in peers) return { kind: "npm-unsupported", framework: label, reason: `The package needs ${label}.` };
   }
@@ -73,9 +74,14 @@ export function detectFlavor(meta) {
  */
 export async function resolveNpmTarget(target, view) {
   if (target.status !== "ok" || target.kind !== "npm" || !target.resolved) return target;
-  const { name, requested } = target.resolved;
+  const { name, requested, subpath } = target.resolved;
   try {
     const meta = await view(`${name}@${requested ?? "latest"}`);
+    // The registry lists a package's exports, so a wrong sub-path is caught here, before anything is installed.
+    if (subpath) {
+      const result = checkExports(meta.exports, subpath);
+      if (result.checked && !result.ok) throw new Error(notExportedMessage({ name, version: meta.version ?? null, subpath, exact: result.exact, patterns: result.patterns }));
+    }
     const flavor = detectFlavor(meta);
     return {
       ...target,

package/src/plan/subpath.js

@@ -0,0 +1,133 @@
+/**
+ * Sub-paths of an npm package: `@scope/pkg/button/v2` imports `button/v2` from `@scope/pkg`.
+ * A package says what it lets people import in its `exports` field. A package without one lets people import any file in it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Split a sub-path into clean segments, or say what's wrong with it. Rejects empty parts, `.` and `..`, and backslashes,
+ * so a sub-path can't point outside the package. A trailing slash is dropped.
+ * @param {string} text
+ * @returns {{ ok: true, subpath: string } | { ok: false, reason: string }}
+ */
+export function cleanSubpath(text) {
+  const trimmed = text.replace(/\/+$/, "");
+  if (!trimmed) return { ok: false, reason: "the sub-path is empty" };
+  if (trimmed.includes("\\")) return { ok: false, reason: "a sub-path uses forward slashes" };
+  const segments = trimmed.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) return { ok: false, reason: 'a sub-path can\'t contain empty parts, "." or ".."' };
+  return { ok: true, subpath: segments.join("/") };
+}
+
+/**
+ * The export keys that name a sub-path (`./button`), and the patterns (`./es/*`), from an `exports` field.
+ * A string, an array, or an object with no `./` keys only exports the package root.
+ */
+function exportKeys(exportsField) {
+  if (!exportsField || typeof exportsField !== "object" || Array.isArray(exportsField)) return { exact: [], patterns: [], hasMap: false };
+  const keys = Object.keys(exportsField).filter((key) => key === "." || key.startsWith("./"));
+  if (keys.length === 0) return { exact: [], patterns: [], hasMap: false };
+  const usable = keys.filter((key) => exportsField[key] !== null);
+  return { exact: usable.filter((key) => !key.includes("*") && key !== "." && key !== "./package.json"), patterns: usable.filter((key) => key.includes("*")), hasMap: true };
+}
+
+/** Does a pattern key like `./es/*` or `./features/*.js` match a sub-path? */
+function matchesPattern(pattern, subpath) {
+  const [before, after] = pattern.slice(2).split("*");
+  return subpath.length >= before.length + after.length && subpath.startsWith(before) && subpath.endsWith(after);
+}
+
+/**
+ * Does the package's `exports` field let a sub-path be imported? Returns the sub-paths to suggest when it doesn't.
+ * `package.json` is always allowed. A package with no exports map isn't judged here, because its files are the answer.
+ * @param {unknown} exportsField
+ * @param {string} subpath
+ * @returns {{ checked: boolean, ok: boolean, exact: string[], patterns: string[] }}
+ */
+export function checkExports(exportsField, subpath) {
+  const { exact, patterns, hasMap } = exportKeys(exportsField);
+  if (!hasMap) {
+    // A string or array exports field means only the root is exported. No field means nothing here can say.
+    return { checked: exportsField !== undefined && exportsField !== null, ok: false, exact: [], patterns: [] };
+  }
+  const key = `./${subpath}`;
+  const ok = key === "./package.json" || exact.includes(key) || patterns.some((pattern) => matchesPattern(pattern, subpath));
+  return { checked: true, ok, exact, patterns };
+}
+
+/**
+ * What's wrong with a sub-path of an installed package, or null when it can be imported.
+ * @param {string} workDir The folder the package was installed into.
+ * @param {string} name
+ * @param {string} subpath
+ * @param {string | null} version
+ * @returns {string | null}
+ */
+export function subpathProblem(workDir, name, subpath, version) {
+  const packageDir = join(workDir, "node_modules", name);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+  } catch {
+    return `${name} was installed, but its package.json couldn't be read to check the sub-path "${subpath}".`;
+  }
+  const result = checkExports(manifest.exports, subpath);
+  if (result.checked) return result.ok ? null : notExportedMessage({ name, version, subpath, exact: result.exact, patterns: result.patterns });
+  return fileExists(packageDir, subpath) ? null : `"${name}/${subpath}" isn't a file in ${name}${version ? `@${version}` : ""}, and the package has no exports map that lists what it offers.`;
+}
+
+/** The extensions a file can be imported without writing, for a package with no exports map. */
+const EXTENSIONS = ["", ".js", ".mjs", ".cjs", ".json", "/index.js", "/index.mjs", "/index.cjs"];
+
+/** Is there a file for this sub-path in an installed package that has no exports map? */
+export function fileExists(packageDir, subpath) {
+  return EXTENSIONS.some((extension) => existsSync(join(packageDir, `${subpath}${extension}`)));
+}
+
+/** How many single-character edits turn one word into another. */
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) row.push(Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)));
+    previous = row;
+  }
+  return previous[b.length];
+}
+
+/** The exports closest to what was asked for: a shared start, a shared last part, or a typo of it. */
+function closest(subpath, exact) {
+  const wanted = subpath.toLowerCase().split("/");
+  const last = wanted[wanted.length - 1];
+  return exact
+    .map((key) => {
+      const parts = key.slice(2).toLowerCase().split("/");
+      const shared = parts.findIndex((part, i) => part !== wanted[i]);
+      const lead = shared === -1 ? parts.length : shared;
+      const tail = parts[parts.length - 1];
+      const rank = lead * 2 + (tail.includes(last) || last.includes(tail) ? 1 : 0) + (distance(last, tail) <= 2 ? 2 : 0);
+      return { key, rank };
+    })
+    .filter((entry) => entry.rank > 0)
+    .sort((a, b) => b.rank - a.rank || a.key.length - b.key.length)
+    .slice(0, 3)
+    .map((entry) => entry.key);
+}
+
+/**
+ * The message for a sub-path a package doesn't offer, with the closest matches first.
+ * @param {{ name: string, version: string | null, subpath: string, exact: string[], patterns: string[] }} input
+ */
+export function notExportedMessage({ name, version, subpath, exact, patterns }) {
+  const spec = (key) => `${name}${key === "." ? "" : key.slice(1)}`;
+  const close = closest(subpath, exact);
+  const shown = exact.slice(0, 12).map(spec);
+  const more = exact.length > shown.length ? `, and ${exact.length - shown.length} more` : "";
+  const parts = [`"${name}/${subpath}" isn't something ${name}${version ? `@${version}` : ""} exports.`];
+  if (close.length) parts.push(`Did you mean ${close.map(spec).join(" or ")}?`);
+  if (exact.length) parts.push(`It exports ${shown.join(", ")}${more}.`);
+  if (patterns.length) parts.push(`It also exports files by pattern: ${patterns.slice(0, 4).map(spec).join(", ")}.`);
+  if (!exact.length && !patterns.length) parts.push("It exports only its main entry.");
+  return parts.join(" ");
+}

package/src/report/comparison.js

@@ -3,11 +3,13 @@ import { num, plural } from "../text.js";
 import {
   ENGINE_NAMES,
   FINDINGS_NOTE,
+  GENERATED_NOTE,
   TIER_NAMES,
   cell,
   code,
   configLabel,
   finish,
+  hasGenerated,
   notTestableLines,
   reportFooter,
   reportHeader,
@@ -15,7 +17,7 @@ import {
   targetSection,
 } from "./parts.js";
 
-const TIER_ORDER = ["rules", "interactions", "computed", "vsr"];
+const TIER_ORDER = ["rules", "interactions", "computed", "conditions", "vsr"];
 
 /** The archetype rows: component archetypes in a fixed order, then whole pages, then Storybook stories. */
 function archetypeKeys(results) {
@@ -67,7 +69,9 @@ function coverageTable(plan, results, tier, keys) {
       // Name the configuration only when there's more than one to tell apart, or the row stands for several stories.
       const withTier = rows.filter((r) => r.configs?.some((c) => c.tiers[tier]));
       const labels = withTier.length > 1 || withTier[0]?.always ? withTier.map((r) => r.label).filter((l) => l && l !== "-") : [];
-      return labels.length ? `${status} (${labels.join("; ")})` : status;
+      const generated = target.archetypes?.[key]?.fixture?.source === "generated" && String(status).startsWith("ran");
+      const base = labels.length ? `${status} (${labels.join("; ")})` : status;
+      return generated ? `${base} (generated fixture)` : base;
     });
     lines.push(`| ${key} | ${cells.join(" | ")} |`);
   }
@@ -104,9 +108,9 @@ function interactionsCell(configs) {
   return parts.filter(Boolean).join("; ");
 }
 
-function computedCell(configs) {
-  const checks = configs.flatMap((c) => c.tiers.computed?.checks ?? []);
-  if (checks.length === 0) return configs.map((c) => c.tiers.computed?.status).find(Boolean) ?? "-";
+function measuredCell(configs, tier) {
+  const checks = configs.flatMap((c) => c.tiers[tier]?.checks ?? []);
+  if (checks.length === 0) return configs.map((c) => c.tiers[tier]?.status).find(Boolean) ?? "-";
   const failed = checks.filter((c) => c.result === "fail").map((c) => code(c.name));
   const unknown = checks.filter((c) => c.result === "undetermined").length;
   const errors = checks.filter((c) => c.result === "error").length;
@@ -123,17 +127,17 @@ function vsrCell(configs) {
 }
 
 function findingsTable(plan, results, key) {
-  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Computed checks", "Virtual screen reader (simulated)"];
+  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Computed checks", "Conditions", "Virtual screen reader (simulated)"];
   const lines = [`| ${head.join(" | ")} |`, `| ${head.map(() => "---").join(" | ")} |`];
   for (const target of results.targets) {
     const planTarget = plan.targets.find((t) => t.id === target.id);
     for (const row of rowsFor(planTarget, target, key)) {
       if (row.note) {
-        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | | |`);
+        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | | | |`);
         continue;
       }
       const c = row.configs;
-      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(computedCell(c))} | ${cell(vsrCell(c))} |`);
+      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(measuredCell(c, "computed"))} | ${cell(measuredCell(c, "conditions"))} | ${cell(vsrCell(c))} |`);
     }
   }
   return lines;
@@ -180,6 +184,7 @@ export function renderComparison({ plan, results }) {
     lines.push(`### ${TIER_NAMES[tier]}${tier === "vsr" ? " (simulated)" : ""}.`, "", ...coverageTable(plan, results, tier, keys), "");
   }
   lines.push(...notTestableLines(results));
+  if (hasGenerated(results)) lines.push(GENERATED_NOTE, "");
 
   lines.push("## Findings.", "", FINDINGS_NOTE, "", ...(o.tiers.includes("rules") ? impactTables(results, o.engines) : []));
   for (const key of keys) {
@@ -187,7 +192,7 @@ export function renderComparison({ plan, results }) {
   }
 
   lines.push("## Details by target.", "", "Every finding, with its elements, rule help, and logs, for each target in turn.", "");
-  for (const target of results.targets) lines.push(targetSection(plan.targets.find((t) => t.id === target.id), target));
+  for (const target of results.targets) lines.push(targetSection(plan.targets.find((t) => t.id === target.id), target, { generatedNote: false }));
   lines.push(...reportFooter(results));
   return finish(lines);
 }