automatica11y 0.4.0 → 0.6.0

package/src/run/audit-npm.js

@@ -1,13 +1,16 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { bundleEntries } from "../harness/bundle.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 { installedVersion, installExtraPackages, installOptionalPeers, installPackage } from "../harness/npm-install.js";
+import { shipsBrowserAssets } from "../frameworks/html.js";
+import { ANGULAR_FLOOR } from "../frameworks/angular.js";
+import { explainAngularError } from "../frameworks/angular-errors.js";
 import { adapterFor, adapterForKind } from "../frameworks/index.js";
-import { subpathProblem } from "../plan/subpath.js";
+import { offeredSubpaths, 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";
@@ -21,6 +24,12 @@ import { failedVsr, runVsr } from "../tiers/vsr.js";
 import { num } from "../text.js";
 import { summarize } from "./summary.js";
 
+/** @typedef {ReturnType<typeof import("../schema.js").parsePlan>} Plan */
+/** @typedef {ReturnType<typeof import("../schema.js").parseResults>["targets"][number]} TargetResult */
+/** @typedef {ReturnType<typeof import("../schema.js").parseMappingFile>[string]} TargetMapping */
+/** @typedef {NonNullable<TargetResult["archetypes"][string]["fixture"]>} FixtureInfo */
+/** @typedef {TargetResult["archetypes"][string]["configs"][number]} FixtureConfig */
+
 /** The states worth checking for each archetype. The first is where a page starts. */
 const STATES = {
   dialog: ["closed", "open"],
@@ -36,12 +45,12 @@ const firstLine = (error) => (error instanceof Error ? error.message : String(er
 /** Page and console errors that mean a fixture didn't mount cleanly. A missing favicon doesn't count. */
 function watchErrors(errors) {
   return (page) => {
-    page.on("pageerror", (error) => errors.push(error.message.split("\n")[0]));
+    page.on("pageerror", (error) => errors.push(explainAngularError(error.message.split("\n")[0])));
     page.on("console", (message) => {
       if (message.type() !== "error") return;
       const text = message.text();
       if (/favicon|Failed to load resource/i.test(text) && !/\.(js|css)\b/.test(text)) return;
-      errors.push(text.split("\n")[0]);
+      errors.push(explainAngularError(text.split("\n")[0]));
     });
   };
 }
@@ -62,6 +71,15 @@ async function bundleWithPeers(options, warnings) {
   }
 }
 
+/** The installed package's own package.json, or an empty object. */
+function readInstalledMeta(workDir, name) {
+  try {
+    return JSON.parse(readFileSync(join(workDir, "node_modules", name, "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 /** 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 adapter = adapterFor(flavor);
@@ -73,12 +91,12 @@ async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
   try {
     const opened = await openPage(browser, `${server.origin}/discover.html`, { beforeGoto: watchErrors(errors) });
     try {
-      await opened.page.waitForFunction(() => /** @type {any} */ (window).__a11yExports !== undefined, undefined, { timeout: 15_000 });
+      await opened.page.waitForFunction(() => window.__a11yExports !== undefined, undefined, { timeout: 15_000 });
     } catch {
       throw new Error(`The package didn't finish loading in the browser${errors.length ? `: ${errors[0]}` : "."}`);
     }
-    const exportsList = await opened.page.evaluate(() => /** @type {any} */ (window).__a11yExports);
-    const tags = await opened.page.evaluate(() => [.../** @type {any} */ (window).__a11yDefined ?? []]);
+    const exportsList = await opened.page.evaluate(() => window.__a11yExports ?? []);
+    const tags = await opened.page.evaluate(() => [...(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 = {};
@@ -98,7 +116,8 @@ async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
         } 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) };
+        const attributes = "observedAttributes" in Element && Array.isArray(Element.observedAttributes) ? Element.observedAttributes : [];
+        out[name] = { attributes: [...attributes], members: [...members], slots: slots.filter(Boolean) };
       }
       return out;
     }, tags);
@@ -151,7 +170,7 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
         }
       }
       await settleAnimations(opened.page);
-      /** @type {Record<string, any>} */
+      /** @type {TargetResult["archetypes"][string]["configs"][number]["tiers"]} */
       const tiers = {};
       for (const tier of plan.options.tiers) {
         if (tier === "interactions" || tier === "computed" || tier === "conditions") continue;
@@ -177,7 +196,8 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
 
 /**
  * Audit one fixture. A library that ships opt-in accessibility features runs once for each `--lib-a11y` value, and each result carries its label.
- * @param {{ browser: any, url: string, archetype: string, plan: any, toggle: boolean }} options
+ * @param {{ browser: import("playwright-core").Browser, url: string, archetype: string, plan: Plan, toggle: boolean }} options
+ * @returns {Promise<{ gap: string } | { configs: FixtureConfig[], hidden: string[] }>}
  */
 async function auditFixture({ browser, url, archetype, plan, toggle }) {
   const values = toggle ? plan.options.libA11y : ["n/a"];
@@ -185,7 +205,7 @@ async function auditFixture({ browser, url, archetype, plan, toggle }) {
   const hidden = [];
   for (const libA11y of values) {
     const outcome = await auditFixturePage({ browser, url, archetype, plan, libA11y });
-    if (outcome.gap) return { gap: toggle ? `With library accessibility ${libA11y}: ${outcome.gap}` : outcome.gap };
+    if ("gap" in outcome) return { gap: toggle ? `With library accessibility ${libA11y}: ${outcome.gap}` : outcome.gap };
     configs.push(...outcome.configs);
     hidden.push(...outcome.hidden);
   }
@@ -195,14 +215,15 @@ 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, files?: Record<string, string> }>}
+ * @param {{ browser: import("playwright-core").Browser, planTarget: Plan["targets"][number], plan: Plan, cwd: string, install?: typeof installPackage }} options
+ * @returns {Promise<{ result: TargetResult, mapping: TargetMapping | 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. This version covers React, Vue 3, and web components.` }, mapping: null };
+    return { result: { ...base, status: "unsupported", reason: `${resolved.framework ?? "This framework"} packages aren't supported.${resolved.framework === "Angular" && resolved.detectedBy ? ` ${resolved.detectedBy}` : ""} This version covers React, Vue 3, Angular ${ANGULAR_FLOOR} and newer, and web components.` }, mapping: null };
   }
   const tmp = mkdtempSync(join(tmpdir(), "automatica11y-npm-"));
   const workDir = join(tmp, "install");
@@ -212,8 +233,9 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
   const servers = [];
   try {
     /** 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 adapterId = adapterForKind(planTarget.kind)?.id;
+    /** @type {"react" | "vue" | "angular" | "html" | "wc" | "unknown"} */
+    let flavor = adapterId === "react" || adapterId === "vue" || adapterId === "angular" || adapterId === "html" || adapterId === "wc" ? adapterId : "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.
@@ -223,25 +245,68 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       if (problem) throw new Error(problem);
     }
 
+    // The other packages of a list target (`npm:a,b`) go into the same folder, so the scripts and styles of one see the others.
+    /** @type {Array<{ name: string, subpath: string | null, version: string | null }>} */
+    const companions = [];
+    const alreadyInstalled = new Set([resolved.name]);
+    for (const companion of planTarget.companions ?? []) {
+      // A second entry for a package that's already in the folder (a stylesheet and a script from one package) needs no second install.
+      const added = alreadyInstalled.has(companion.name) ? { warnings: [], version: installedVersion(workDir, companion.name) } : await install({ dir: workDir, name: companion.name, version: companion.version, flavor: "unknown" });
+      warnings.push(...added.warnings);
+      if (companion.subpath) {
+        const problem = subpathProblem(workDir, companion.name, companion.subpath, added.version ?? companion.version);
+        if (problem) throw new Error(problem);
+      }
+      alreadyInstalled.add(companion.name);
+      companions.push({ name: companion.name, subpath: companion.subpath ?? null, version: added.version ?? companion.version });
+    }
+
     // 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 });
+    // What the install left behind that an adapter's entry needs to know about, such as whether zone.js came with the library.
+    const listed = [{ name: resolved.name, subpath: resolved.subpath ?? null }, ...companions.map((c) => ({ name: c.name, subpath: c.subpath }))];
+    let context = adapterForKind(planTarget.kind)?.inspect?.(workDir, listed) ?? {};
+
+    // Plain HTML has no exports or elements to list. What it loads came from the target itself.
+    let found = flavor === "html" ? { exports: [], tags: [], facts: {} } : 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";
+      // Nothing to load as a component, but the package ships stylesheets or browser scripts: it's plain HTML.
+      else if (shipsBrowserAssets(readInstalledMeta(workDir, resolved.name))) {
+        flavor = "html";
+        found = { exports: [], tags: [], facts: {} };
+        context = adapterFor("html").inspect?.(workDir, listed) ?? {};
+      }
+    }
+    if (flavor === "html") {
+      const assets = /** @type {any} */ (context).assets;
+      if (!assets || (assets.styles.length === 0 && assets.scripts.length === 0)) {
+        warnings.push("The target didn't name a stylesheet or a script, so the page loaded none and the templates ran on the browser's own styles. Name them as sub-paths, such as npm:name/style.css.");
+      }
     }
     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 components for a supported framework and defines no custom elements.", warnings }, mapping: null };
+      // Some packages keep their components in sub-paths and leave the main entry nearly empty.
+      const hints = resolved.subpath ? [] : offeredSubpaths(workDir, resolved.name);
+      const where = hints.length ? ` Some packages keep their components in sub-paths, and this one exports ${hints.join(", ")}. Try one, for example npm:${hints[0]}.` : "";
+      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.${where}`, warnings }, mapping: null };
     }
 
     const candidates = candidateMapping({ flavor, exports: found.exports, tags: found.tags });
+    if (flavor === "html") {
+      // There's no component to find, so an archetype is either a fixture someone writes or a gap that says so.
+      for (const [archetype, entry] of Object.entries(candidates)) {
+        if (adapterFor("html").template(archetype, "")) Object.assign(entry, { status: "template", reason: undefined });
+        else if (entry.status === "no-match") Object.assign(entry, { status: "needs-fixture", reason: `Plain HTML has no component to find, so the ${archetype} archetype needs a fixture someone writes.` });
+      }
+    }
     const adapter = adapterFor(flavor);
     const wanted = plan.options.archetypes ?? ARCHETYPES;
-    /** @type {Record<string, any>} */
+    /** @type {TargetMapping} */
     const mapping = {};
-    /** @type {Record<string, any>} */
+    /** @type {TargetResult["archetypes"]} */
     const archetypes = {};
     const gaps = [];
     const hidden = [];
@@ -276,7 +341,7 @@ 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 = adapter.template(archetype, importSpec, flavor === "wc" ? entry.tag : entry.export);
+        const source = adapter.template(archetype, importSpec, flavor === "wc" ? entry.tag : entry.export, found.exports.find((e) => e.name === entry.export));
         if (source) {
           entry.status = "template";
           delete entry.reason;
@@ -284,13 +349,13 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
           writeFileSync(fixture, source);
         }
       }
-      /** @type {any} */
+      /** @type {FixtureInfo | null} */
       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) });
+        const generated = await generateFixture({ browser, adapter, archetype, entry, found, explicit: Boolean(user.export), pkg: importSpec, tmp, workDir, buildDir, context, getServer, bundle: (options) => bundleWithPeers(options, warnings) });
         attempts = generated.attempts;
         generationTried = attempts.length > 0;
         if (generated.ok && generated.winner) {
@@ -320,7 +385,7 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       }
       const entryFile = join(tmp, "entries", `${archetype}-entry.js`);
       mkdirSync(join(tmp, "entries"), { recursive: true });
-      writeFileSync(entryFile, adapter.entry(fixture, importSpec));
+      writeFileSync(entryFile, adapter.entry(fixture, importSpec, context));
       try {
         await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
         runnable[archetype] = `/${archetype}.html`;
@@ -337,10 +402,9 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       const live = await serveStatic(buildDir);
       servers.push(live);
       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) {
+        if ("gap" in outcome) {
           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";
@@ -364,11 +428,14 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
           name: resolved.name,
           subpath: resolved.subpath ?? null,
           version: installed.version ?? resolved.version,
+          ...(companions.length ? { companions } : {}),
           flavor,
           framework: resolved.framework ?? null,
           react: installed.react,
           reactDom: installed.reactDom,
           vue: installed.vue ?? null,
+          angular: installed.angular ?? null,
+          ...(flavor === "html" ? { assets: /** @type {any} */ (context).assets } : {}),
           tags: flavor === "wc" ? found.tags : [],
         },
         summary: (() => {

package/src/run/fail-check.js

@@ -1,5 +1,13 @@
 import { IMPACTS } from "../schema.js";
 
+/**
+ * @typedef {{ impact?: string | null, toolkitLevel?: number | null }} FailFinding
+ * @typedef {{ status?: string, violations?: FailFinding[] }} FailEngineResult
+ * @typedef {{ tiers: { rules?: { engines?: Record<string, FailEngineResult> } } }} FailConfigResult
+ * @typedef {{ configs: FailConfigResult[] }} FailArchetypeResult
+ * @typedef {{ id: string, status: string, archetypes: Record<string, FailArchetypeResult> }} FailTarget
+ */
+
 const RANK = Object.fromEntries(IMPACTS.map((impact, index) => [impact, index]));
 
 /** All findings an engine reported for one target, across every archetype and configuration. */
@@ -28,8 +36,8 @@ export function countIbmHits(target, threshold) {
  * Decide whether the run trips its fail check. Each engine has its own threshold, and counts are never added across engines.
  * `any` trips a target when any checked engine hits. `all` trips it only when every checked engine hits.
  * A target that failed, or an engine that failed, counts as no hit.
- * @param {Array<any>} targets Target results.
- * @param {{ mode: string, axe: string | null, ibm: number | null } | null} fail
+ * @param {FailTarget[]} targets Target results.
+ * @param {ReturnType<typeof import("../schema.js").parsePlan>["options"]["fail"]} fail
  */
 export function evaluateFailCheck(targets, fail) {
   if (!fail) return null;

package/src/run/generate-fixture.js

@@ -14,18 +14,19 @@ const firstLine = (error) => (error instanceof Error ? error.message : String(er
  *   adapter: import("../frameworks/index.js").Adapter,
  *   archetype: string,
  *   entry: { export?: string, tag?: string },
- *   found: { exports: any[], tags: string[], facts: Record<string, any> },
+ *   found: { exports: PackageExport[], tags: string[], facts: Record<string, { attributes: string[], members: string[], slots: string[] }> },
  *   pkg: string,
  *   explicit?: boolean,
+ *   context?: Record<string, unknown>,
  *   tmp: string,
  *   workDir: string,
  *   buildDir: string,
  *   getServer: () => Promise<{ origin: string }>,
- *   bundle: (options: any) => Promise<unknown>,
+ *   bundle: (options: Parameters<typeof import("../harness/bundle.js").bundleEntries>[0]) => 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 }) {
+export async function generateFixture({ browser, adapter, archetype, entry, found, explicit = false, pkg, tmp, workDir, buildDir, context = {}, 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: [] };
 
@@ -37,7 +38,7 @@ export async function generateFixture({ browser, adapter, archetype, entry, foun
     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));
+    writeFileSync(entryFile, adapter.entry(file, pkg, context));
     return { candidate, name, file, entryFile, bundled: null };
   });
 

package/src/run/run-plan.js

@@ -26,14 +26,14 @@ 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-vue", "npm-wc", "npm-unsupported"]);
+const NPM_KINDS = new Set(["npm", "npm-react", "npm-vue", "npm-angular", "npm-html", "npm-wc", "npm-unsupported"]);
 const UNSUPPORTED_KIND = (kind) => `${kind} targets aren't supported.`;
 
 /** Audit one page and return its target result. */
 async function auditPage(browser, url, planTarget, plan, extraWarnings) {
   const opened = await openPage(browser, url);
   try {
-    /** @type {Record<string, any>} */
+    /** @type {ReturnType<typeof import("../schema.js").parseResults>["targets"][number]["archetypes"][string]["configs"][number]["tiers"]} */
     const tiers = {};
     for (const tier of plan.options.tiers) {
       if (tier === "rules") {
@@ -71,7 +71,7 @@ async function auditStory(browser, base, story, plan) {
   const opened = await openPage(browser, storyUrl(base, story.id));
   try {
     await waitForStory(opened.page);
-    /** @type {Record<string, any>} */
+    /** @type {ReturnType<typeof import("../schema.js").parseResults>["targets"][number]["archetypes"][string]["configs"][number]["tiers"]} */
     const tiers = {};
     for (const tier of plan.options.tiers) {
       tiers[tier] =
@@ -201,7 +201,7 @@ function describeResult(target) {
 
 /**
  * Run a plan: check the environment, launch one browser, audit each target, write results.json and report.md.
- * @param {any} plan
+ * @param {ReturnType<typeof import("../schema.js").parsePlan>} plan
  * @param {import("../commands/common.js").Io} io
  * @returns {Promise<number>} The exit code.
  */
@@ -232,14 +232,15 @@ export async function runPlan(plan, io) {
     /** Fixtures the tool generated, by path under the output folder. */
     const generatedFiles = {};
     for (const planTarget of plan.targets) {
-      const { result, mapping, files } = await runTarget(browser, planTarget, plan, io);
+      const targetRun = await runTarget(browser, planTarget, plan, io);
+      const { result, mapping } = targetRun;
       targets.push(result);
-      if (files) Object.assign(generatedFiles, files);
+      if ("files" in targetRun && targetRun.files) Object.assign(generatedFiles, targetRun.files);
       if (mapping) {
         mappings[planTarget.id] = mapping;
         planTarget.mapping = mapping;
       }
-      if (result.npm) planTarget.kind = adapterFor(result.npm.flavor).kind;
+      if ("npm" in result && result.npm) planTarget.kind = adapterFor(result.npm.flavor).kind;
     }
 
     const results = parseResults({

package/src/run/summary.js

@@ -1,6 +1,6 @@
 /** Roll the engine results up into counts. Impact counts belong to axe and Toolkit-level counts belong to IBM. */
 export function summarize(archetypes, engines, gaps = []) {
-  /** @type {any} */
+  /** @type {ReturnType<typeof import("../schema.js").parseResults>["targets"][number]["summary"]} */
   const summary = { engines: {}, gaps, notTestable: [] };
   for (const engine of engines) {
     const results = Object.values(archetypes).flatMap((a) => a.configs.map((c) => c.tiers.rules?.engines?.[engine]).filter(Boolean));

package/src/schema.js

@@ -9,7 +9,7 @@ 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", "live-region", "chart"];
-export const FLAVORS = ["react", "vue", "wc"];
+export const FLAVORS = ["react", "vue", "angular", "html", "wc"];
 export const MAPPING_STATUSES = ["template", "authored", "generated", "needs-fixture", "no-match"];
 
 /** What a candidate mapping says about one archetype of one npm target. */
@@ -49,7 +49,7 @@ export function parseMappingFile(input) {
   return result.output;
 }
 
-export const TARGET_KINDS = ["npm", "npm-react", "npm-vue", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
+export const TARGET_KINDS = ["npm", "npm-react", "npm-vue", "npm-angular", "npm-html", "npm-wc", "npm-unsupported", "npm-non-ui", "storybook", "url", "html-file", "static-dir"];
 
 const nullableString = v.nullable(v.string());
 
@@ -62,6 +62,8 @@ export const TargetSchema = v.object({
   kind: v.nullable(v.picklist(TARGET_KINDS)),
   evidenceLevel: v.nullable(v.picklist(["component", "page"])),
   resolved: v.nullable(v.record(v.string(), nullableString)),
+  /** The other packages of an npm list target (`npm:a,b`), which install beside the primary one. */
+  companions: v.optional(v.array(v.object({ name: v.string(), requested: nullableString, version: nullableString, subpath: nullableString }))),
   mapping: v.nullable(v.record(v.string(), MappingEntrySchema)),
 });
 
@@ -230,11 +232,16 @@ export const TargetResultSchema = v.object({
       /** 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,
+      /** The other packages of a list target (`npm:a,b`), installed beside the primary one. */
+      companions: v.optional(v.array(v.object({ name: v.string(), subpath: nullableString, version: nullableString }))),
       flavor: v.picklist(FLAVORS),
       framework: nullableString,
       react: nullableString,
       reactDom: nullableString,
       vue: v.optional(nullableString),
+      angular: v.optional(nullableString),
+      /** For plain HTML, the stylesheets and scripts the page loaded, as `package/sub-path`. */
+      assets: v.optional(v.object({ styles: v.array(v.string()), scripts: v.array(v.string()) })),
       tags: v.array(v.string()),
     }),
   ),

package/src/tiers/computed/checks.js

@@ -9,6 +9,8 @@ import { num } from "../../text.js";
 import { criterionRef } from "../../wcag/index.js";
 import { contrastOver, contrastRatio, formatRatio, ringIsEnough, textThreshold } from "./color.js";
 
+/** @typedef {{ key: number, text: string, color: number[] | null, size: number, weight: string, backdrop: number[] | null, undetermined: string | null }} TextPart */
+
 const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
 const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
 const na = (detail) => ({ result: "not-applicable", detail });
@@ -31,7 +33,7 @@ const TEXT_CONTRAST = {
   name: "text-contrast-by-state",
   criteria: ["1.4.3"],
   async run(ctx) {
-    /** @type {Array<{ state: string, parts: any[] }>} */
+    /** @type {Array<{ state: string, parts: TextPart[] }>} */
     const states = [];
     const measure = async (state) => states.push({ state, parts: (await ctx.page.evaluate(() => window.__a11yMeasure.text())) ?? [] });
     await parkPointer(ctx);

package/src/tiers/conditions/kit.js

@@ -33,8 +33,8 @@ export function installConditions() {
     describe,
     /** Every animation and transition running right now. */
     animations() {
-      return document.getAnimations().map((/** @type {any} */ animation) => {
-        const effect = /** @type {any} */ (animation.effect);
+      return document.getAnimations().map((animation) => {
+        const effect = animation.effect instanceof KeyframeEffect ? animation.effect : null;
         const timing = effect?.getComputedTiming?.() ?? {};
         const keyframes = effect?.getKeyframes?.() ?? [];
         const props = [...new Set(keyframes.flatMap((frame) => Object.keys(frame)).filter((key) => !IGNORED_KEYS.has(key)))];
@@ -42,7 +42,7 @@ export function installConditions() {
         const iterations = timing.iterations === Infinity ? "infinite" : timing.iterations;
         return {
           kind: animation.constructor.name,
-          name: animation.animationName ?? animation.transitionProperty ?? "",
+          name: animation instanceof CSSAnimation ? animation.animationName : animation instanceof CSSTransition ? animation.transitionProperty : "",
           target: describe(target),
           duration: typeof timing.duration === "number" ? timing.duration : null,
           iterations,

package/src/tiers/interactions/archetypes.js

@@ -34,7 +34,10 @@ const COMMON = [
       await ctx.page.evaluate(() => window.__a11y.remember());
       const clip = ctx.clipAround(focused.box);
       const shotFocused = await ctx.page.screenshot({ clip });
-      await ctx.page.evaluate(() => /** @type {any} */ (window).__a11yLast?.blur());
+      await ctx.page.evaluate(() => {
+        const last = window.__a11yLast;
+        if (last && "blur" in last && typeof last.blur === "function") last.blur();
+      });
       await ctx.settle();
       const unfocused = await ctx.page.evaluate(() => window.__a11y.lastSnapshot());
       const changed = focusIndicatorChanges(focused.parts, unfocused?.parts);
@@ -422,7 +425,8 @@ export const ARCHETYPE_CHECKS = {
       async run(ctx) {
         const facts = await ctx.page.evaluate(() => {
           const c = window.__a11y.queryDeep("[data-a11y-trigger]");
-          return { tag: c?.localName, type: c?.getAttribute("type") ?? "text", required: c?.hasAttribute("required"), pattern: c?.hasAttribute("pattern"), minlength: c?.hasAttribute("minlength"), valid: c?.checkValidity?.() ?? true };
+          const validity = c && "checkValidity" in c && typeof c.checkValidity === "function" ? c.checkValidity() : undefined;
+          return { tag: c?.localName, type: c?.getAttribute("type") ?? "text", required: c?.hasAttribute("required"), pattern: c?.hasAttribute("pattern"), minlength: c?.hasAttribute("minlength"), valid: validity ?? true };
         });
         const control = ctx.trigger;
         const before = await ctx.page.evaluate(() => window.__a11y.errorInfo());

package/src/tiers/interactions/focus-indicator.js

@@ -1,9 +1,11 @@
+/** @typedef {{ outlineStyle: string, outlineWidth: string, outlineColor: string, boxShadow: string, borderTopStyle: string, borderTopColor: string, borderTopWidth: string, backgroundColor: string, color: string, textDecorationLine: string, rendered: boolean }} FocusPart */
+
 /**
  * Compare the resolved styles of a control with and without keyboard focus, and say which changes can show a focus indicator.
  * A change counts only if a person could see it: an outline with a width and a color, a box shadow, a border, a color change,
  * a text decoration, or an element that appeared inside. An outline offset alone doesn't count, because it moves nothing visible.
- * @param {Record<string, Record<string, any>>} focused Parts of the focused control, keyed by where they are.
- * @param {Record<string, Record<string, any>> | undefined} unfocused The same parts without focus.
+ * @param {Record<string, FocusPart>} focused Parts of the focused control, keyed by where they are.
+ * @param {Record<string, FocusPart> | undefined} unfocused The same parts without focus.
  * @returns {string[]} Each change, such as `the element: outline`.
  */
 export function focusIndicatorChanges(focused, unfocused) {

package/src/tiers/interactions/helpers.js

@@ -120,7 +120,8 @@ export function installHelpers() {
         clicks: window.__a11yClicks,
         triggerTag: trigger?.localName ?? null,
         triggerRole: trigger?.getAttribute("role") ?? null,
-        expanded: trigger?.getAttribute("aria-expanded") ?? null,
+        // A native disclosure (<summary> in <details>) says whether it's open with the details element's own state, not an attribute.
+        expanded: trigger?.getAttribute("aria-expanded") ?? (trigger?.localName === "summary" && trigger.parentElement?.localName === "details" ? String(trigger.parentElement.open) : null),
         rootExists: Boolean(root),
         rootVisible: visible(root),
         rootModal: root?.getAttribute("aria-modal") === "true" || root?.getAttribute("role") === "alertdialog",

package/src/tiers/rules/ibm.js

@@ -17,9 +17,9 @@ export const helpUrl = (ruleId) => `https://able.ibm.com/rules/archives/latest/d
 
 /**
  * Group raw IBM results into findings, one per rule and kind, with the first few nodes.
- * @param {Array<{ ruleId: string, message: string, dom?: string, snippet?: string }>} items
+ * @param {Array<{ ruleId: string, message: string, value: string[], dom?: string, snippet?: string }>} items
  * @param {Map<string, { wcag: string[], toolkitLevel: number | null }>} ruleInfo
- * @param {(item: any) => string} kindOf
+ * @param {(item: { value: string[] }) => string} kindOf
  * @param {number} maxNodes
  */
 function group(items, ruleInfo, kindOf, maxNodes, withKind) {

package/src/tiers/rules/index.js

@@ -19,7 +19,7 @@ export async function runRules(page, { engines, wcag, level, maxNodes = 5, scope
       engines: Object.fromEntries(engines.map((engine) => [engine, { status: "not-testable", reason }])),
     };
   }
-  /** @type {Record<string, any>} */
+  /** @type {NonNullable<ReturnType<typeof import("../../schema.js").parseResults>["targets"][number]["archetypes"][string]["configs"][number]["tiers"][string]["engines"]>} */
   const results = {};
   for (const engine of engines) {
     try {