automatica11y 0.4.1 → 0.6.0

package/src/plan/classify.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { cleanSubpath } from "./subpath.js";
 
 /**
- * @typedef {"npm" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
+ * @typedef {"npm" | "npm-react" | "npm-vue" | "npm-angular" | "npm-html" | "npm-wc" | "npm-unsupported" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
  * @typedef {{
  *   input: string,
  *   label: string | null,
@@ -15,9 +15,10 @@ import { cleanSubpath } from "./subpath.js";
  *   kind: TargetKind | null,
  *   evidenceLevel: "component" | "page" | null,
  *   resolved: Record<string, string | null> | null,
+ *   companions?: Array<{ name: string, requested: string | null, version: string | null, subpath: string | null }>,
  * }} ClassifiedTarget
  * @typedef {(url: string | URL, init?: { signal?: AbortSignal, redirect?: string }) => Promise<{ ok: boolean, status: number, text(): Promise<string> }>} FetchLike
- * @typedef {{ cwd?: string, home?: string, fetch?: FetchLike, timeoutMs?: number, npmView?: (spec: string) => Promise<any> }} ClassifyContext
+ * @typedef {{ cwd?: string, home?: string, fetch?: FetchLike, timeoutMs?: number, npmView?: (spec: string) => Promise<unknown> }} ClassifyContext
  */
 
 const LOCAL_PATH = /^(\.{1,2}(\/|$)|\/|~(\/|$)|file:)/;
@@ -123,30 +124,57 @@ async function classifyUrl(spec, base, ctx) {
   }
 }
 
-/** @param {string} spec @param {{ input: string, label: string | null, name: string }} base @returns {ClassifiedTarget} */
-function classifyNpm(spec, base) {
+/**
+ * Read one npm spec: `name`, `name@version`, or either with a sub-path.
+ * @param {string} spec
+ * @returns {{ name: string, requested: string | null, subpath: string | null } | { error: string }}
+ */
+function parseNpmSpec(spec) {
   const match = NPM_NAME.exec(spec);
   if (!match) {
-    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);
+    if (/[A-Z]/.test(spec) && NPM_NAME.test(spec.toLowerCase())) return { error: `"${spec}" isn't a valid package name. npm package names are lowercase.` };
+    return { error: `"${spec}" isn't a valid npm package name. Write npm:name, npm:@scope/name, or npm:name@version.` };
   }
   const [, scope, name, version, rawSubpath] = match;
-  if (version === "") return failed(`"${spec}" ends with @ but has no version.`, base);
+  if (version === "") return { error: `"${spec}" ends with @ but has no version.` };
   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);
+    if ("reason" in cleaned) return { error: `"${spec}" isn't a valid sub-path: ${cleaned.reason}. Write npm:name/sub/path or npm:name@version/sub/path.` };
     subpath = /** @type {{ subpath: string }} */ (cleaned).subpath;
   }
-  const full = scope ? `@${scope}/${name}` : name;
+  return { name: scope ? `@${scope}/${name}` : name, requested: version ?? null, subpath };
+}
+
+/**
+ * An npm target. A comma-separated list (`npm:a,b@1.2`) is one target made of several packages that install into one folder.
+ * The first is the primary: it names the target and decides the framework. The rest are companions, such as a script package
+ * that goes with a stylesheet package.
+ * @param {string} spec @param {{ input: string, label: string | null, name: string }} base @returns {ClassifiedTarget}
+ */
+function classifyNpm(spec, base) {
+  const entries = spec.split(",").map((entry) => entry.trim());
+  if (entries.length > 1 && entries.some((entry) => entry === "")) {
+    return failed(`"${spec}" has an empty entry in its list. Write the packages with commas and no spaces, for example npm:a,b.`, base);
+  }
+  const parsed = entries.map(parseNpmSpec);
+  for (const entry of parsed) if ("error" in entry) return failed(entry.error, base);
+  const [primary, ...companions] = /** @type {Array<{ name: string, requested: string | null, subpath: string | null }>} */ (parsed);
+  const seen = new Set();
+  for (const entry of [primary, ...companions]) {
+    const key = `${entry.name}/${entry.subpath ?? ""}`;
+    if (seen.has(key)) return failed(`"${entry.name}${entry.subpath ? `/${entry.subpath}` : ""}" is in the list more than once.`, base);
+    seen.add(key);
+  }
   return {
     ...base,
-    name: base.name || (subpath ? `${full}/${subpath}` : full),
+    name: base.name || (primary.subpath ? `${primary.name}/${primary.subpath}` : primary.name),
     status: "ok",
     reason: null,
     kind: "npm",
     evidenceLevel: "component",
-    resolved: { name: full, requested: version ?? null, version: null, subpath },
+    resolved: { name: primary.name, requested: primary.requested, version: null, subpath: primary.subpath },
+    ...(companions.length ? { companions: companions.map((c) => ({ name: c.name, requested: c.requested, version: null, subpath: c.subpath })) } : {}),
   };
 }
 

package/src/plan/mapping.js

@@ -39,14 +39,14 @@ export function score(archetype, name) {
 }
 
 /**
- * Guess which exports (React or Vue) or tags (web components) stand for each archetype.
+ * Guess which exports (React, Vue, or Angular) 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" | "vue" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
- * @returns {Record<string, any>}
+ * @param {{ flavor: "react" | "vue" | "angular" | "html" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
+ * @returns {ReturnType<typeof parseMappingFile>[string]}
  */
 export function candidateMapping({ flavor, exports = [], tags = [] }) {
   const names = flavor === "wc" ? tags : exports.filter((e) => /^[A-Z]/.test(e.name)).map((e) => e.name);
-  /** @type {Record<string, any>} */
+  /** @type {ReturnType<typeof parseMappingFile>[string]} */
   const mapping = {};
   for (const archetype of ARCHETYPES) {
     const ranked = names
@@ -97,7 +97,7 @@ export function findAuthoredFixture({ cwd, targetId, archetype, mapped }) {
     const file = resolve(cwd, mapped.fixture);
     return existsSync(file) ? file : null;
   }
-  for (const ext of ["jsx", "js"]) {
+  for (const ext of ["jsx", "js", "ts", "html"]) {
     const file = resolve(cwd, "fixtures", targetId, `${archetype}.${ext}`);
     if (existsSync(file)) return file;
   }

package/src/plan/resolve-npm.js

@@ -1,10 +1,10 @@
 import { execFile } from "node:child_process";
+import { isAsset } from "../frameworks/html.js";
 import { ADAPTERS } from "../frameworks/index.js";
 import { checkExports, notExportedMessage } from "./subpath.js";
 
-const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports"];
+const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports", "style", "unpkg", "jsdelivr"];
 const OTHER_FRAMEWORKS = {
-  "@angular/core": "Angular",
   svelte: "Svelte",
   "solid-js": "Solid",
   preact: "Preact",
@@ -13,11 +13,16 @@ const OTHER_FRAMEWORKS = {
 };
 const WEB_COMPONENT_BASES = ["lit", "lit-element", "@lit/reactive-element", "@stencil/core", "@microsoft/fast-element", "@polymer/polymer"];
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Read a package's registry metadata without installing it.
  * @param {string} spec `name`, `name@version`, or `name@range`
  * @param {{ timeoutMs?: number }} [options]
- * @returns {Promise<any>} The metadata. Throws an Error with a plain reason when the package can't be read.
+ * @returns {Promise<unknown>} The metadata. Throws an Error with a plain reason when the package can't be read.
  */
 export function npmView(spec, { timeoutMs = 60_000 } = {}) {
   return new Promise((resolve, reject) => {
@@ -45,48 +50,73 @@ export function npmView(spec, { timeoutMs = 60_000 } = {}) {
 }
 
 /**
- * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue.
+ * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue, then Angular.
  * `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-vue" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
+ * @param {unknown} meta
+ * @returns {{ kind: "npm-react" | "npm-vue" | "npm-angular" | "npm-html" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
  */
 export function detectFlavor(meta) {
-  const peers = meta.peerDependencies ?? {};
-  const deps = meta.dependencies ?? {};
-  const react = /** @type {any} */ (ADAPTERS.react.detect(meta));
+  const data = isRecord(meta) ? meta : {};
+  const peers = isRecord(data.peerDependencies) ? data.peerDependencies : {};
+  const deps = isRecord(data.dependencies) ? data.dependencies : {};
+  const react = ADAPTERS.react.detect(data);
   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 (data.customElements) return { kind: "npm-wc", framework: "Web components", reason: "The package has a customElements manifest." };
+  const vue = ADAPTERS.vue.detect(data);
   if (vue) return vue;
+  const angular = ADAPTERS.angular.detect(data);
+  if (angular) return angular;
   for (const [name, label] of Object.entries(OTHER_FRAMEWORKS)) {
     if (name in peers) return { kind: "npm-unsupported", framework: label, reason: `The package needs ${label}.` };
   }
   const base = WEB_COMPONENT_BASES.find((name) => name in deps || name in peers);
   if (base) return { kind: "npm-wc", framework: "Web components", reason: `The package builds on ${base}.` };
+  const html = ADAPTERS.html.detect(data);
+  if (html) return html;
   return { kind: "npm", framework: null, reason: "The metadata doesn't say. The run decides after it loads the package." };
 }
 
 /**
  * Fill in a classified npm target: the concrete version and the framework guess.
  * @param {import("./classify.js").ClassifiedTarget} target
- * @param {(spec: string) => Promise<any>} view
+ * @param {(spec: string) => Promise<unknown>} view
  * @returns {Promise<import("./classify.js").ClassifiedTarget>}
  */
 export async function resolveNpmTarget(target, view) {
   if (target.status !== "ok" || target.kind !== "npm" || !target.resolved) return target;
   const { name, requested, subpath } = target.resolved;
   try {
-    const meta = await view(`${name}@${requested ?? "latest"}`);
+    const metadata = await view(`${name}@${requested ?? "latest"}`);
+    if (!isRecord(metadata)) throw new Error("npm returned package metadata in an unreadable shape.");
+    const meta = metadata;
     // 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 }));
+      if (result.checked && !result.ok) throw new Error(notExportedMessage({ name, version: typeof meta.version === "string" ? meta.version : null, subpath, exact: result.exact, patterns: result.patterns }));
+    }
+    let flavor = detectFlavor(meta);
+    // A list that names a stylesheet or a script (`npm:a/components.css,b/interactions.iife.js`) is plain HTML when the metadata names no framework.
+    if (flavor.kind === "npm" && [target.resolved.subpath, ...(target.companions ?? []).map((c) => c.subpath)].some(isAsset)) {
+      flavor = { kind: "npm-html", framework: "HTML", reason: "The target names a stylesheet or a script to load." };
+    }
+    // Each companion is looked up the same way, so a wrong name, version, or sub-path fails here, before anything is installed.
+    /** @type {Array<{ name: string, requested: string | null, version: string | null, subpath: string | null }>} */
+    const companions = [];
+    for (const companion of target.companions ?? []) {
+      const found = await view(`${companion.name}@${companion.requested ?? "latest"}`);
+      if (!isRecord(found)) throw new Error(`npm returned metadata for ${companion.name} in an unreadable shape.`);
+      const version = typeof found.version === "string" ? found.version : null;
+      if (companion.subpath) {
+        const result = checkExports(found.exports, companion.subpath);
+        if (result.checked && !result.ok) throw new Error(notExportedMessage({ name: companion.name, version, subpath: companion.subpath, exact: result.exact, patterns: result.patterns }));
+      }
+      companions.push({ ...companion, version });
     }
-    const flavor = detectFlavor(meta);
     return {
       ...target,
-      kind: /** @type {any} */ (flavor.kind),
-      resolved: { ...target.resolved, version: meta.version ?? null, framework: flavor.framework, detectedBy: flavor.reason },
+      kind: flavor.kind,
+      resolved: { ...target.resolved, version: typeof meta.version === "string" ? meta.version : null, framework: flavor.framework, detectedBy: flavor.reason },
+      ...(companions.length ? { companions } : {}),
     };
   } catch (error) {
     return { ...target, status: "failed", reason: error instanceof Error ? error.message : String(error), kind: null, evidenceLevel: null, resolved: null };

package/src/plan/subpath.js

@@ -77,6 +77,23 @@ export function subpathProblem(workDir, name, subpath, version) {
   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.`;
 }
 
+/**
+ * Sub-paths an installed package offers, as specs a person could pass (`@scope/pkg/button`), for a message that says where
+ * to look when a package's main entry has no components. Patterns and `package.json` are left out.
+ * @param {string} workDir
+ * @param {string} name
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+export function offeredSubpaths(workDir, name, limit = 4) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(workDir, "node_modules", name, "package.json"), "utf8"));
+    return exportKeys(manifest.exports).exact.slice(0, limit).map((key) => `${name}${key.slice(1)}`);
+  } catch {
+    return [];
+  }
+}
+
 /** 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"];
 

package/src/report/comparison.js

@@ -10,6 +10,8 @@ import {
   configLabel,
   finish,
   hasGenerated,
+  hasNativeTemplates,
+  NATIVE_NOTE,
   notTestableLines,
   reportFooter,
   reportHeader,
@@ -168,7 +170,7 @@ function impactTables(results, engines) {
 /**
  * Render report.md for a comparison of two or more targets.
  * Every target ran with the same settings, so the columns line up. A gap or a failure shows in its cell, and never reads as a pass.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderComparison({ plan, results }) {
   const o = plan.options;
@@ -185,6 +187,7 @@ export function renderComparison({ plan, results }) {
   }
   lines.push(...notTestableLines(results));
   if (hasGenerated(results)) lines.push(GENERATED_NOTE, "");
+  if (hasNativeTemplates(results)) lines.push(NATIVE_NOTE, "");
 
   lines.push("## Findings.", "", FINDINGS_NOTE, "", ...(o.tiers.includes("rules") ? impactTables(results, o.engines) : []));
   for (const key of keys) {

package/src/report/index.js

@@ -3,7 +3,7 @@ import { renderSingleReport } from "./single.js";
 
 /**
  * Render report.md. A comparison of two or more targets gets the side-by-side report. Anything else gets the single report.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderReport(input) {
   return input.plan.command === "compare" && input.results.targets.length > 1 ? renderComparison(input) : renderSingleReport(input);

package/src/report/parts.js

@@ -2,6 +2,8 @@ import { adapterFor } from "../frameworks/index.js";
 import { criterion, criterionName, wcagAttribution } from "../wcag/index.js";
 import { cap, num, plural } from "../text.js";
 
+/** @typedef {NonNullable<ReturnType<typeof import("../schema.js").parseResults>["targets"][number]["archetypes"][string]["configs"][number]["tiers"][string]["flags"]>[number]} VsrFlag */
+
 /** Markdown helpers. */
 export const cell = (text) => String(text ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
 export const code = (text) => `\`${String(text).replace(/`/g, "'")}\``;
@@ -162,7 +164,7 @@ export function storybookSection(planTarget, target) {
   }
   const walks = Object.entries(target.archetypes).map(([key, a]) => ({ id: key.replace(/^story:/, ""), vsr: a.configs[0]?.tiers.vsr })).filter((w) => w.vsr?.status === "ran");
   if (walks.length) {
-    /** @type {Map<string, { flag: any, stories: string[] }>} */
+    /** @type {Map<string, { flag: VsrFlag, stories: string[] }>} */
     const byFlag = new Map();
     for (const { id, vsr } of walks) for (const flag of vsr.flags) {
       const key = `${flag.type}|${flag.phrase}`;
@@ -265,6 +267,14 @@ export function hasGenerated(results) {
   return results.targets.some((t) => Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "generated"));
 }
 
+/** True when a plain HTML target ran from a native-markup template. */
+export function hasNativeTemplates(results) {
+  return results.targets.some((t) => t.npm?.flavor === "html" && Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "template"));
+}
+
+/** What a plain HTML template is, and what it can't say about a package. */
+export const NATIVE_NOTE = "**Native markup templates.** For a plain HTML target the tool used bare native markup (a button, a link, a fieldset, a dialog, details, a popover) with none of the package's classes, so these results show what the package's styles and scripts do to ordinary elements. They don't test a component the package built, and a pass here never means the package's own components pass. A check that needs script behavior the markup doesn't have, such as arrow keys in a menu, measures the bare markup and not the package. Bring a fixture of your own to test the package's components.";
+
 /** What "generated" means, for any report that has one. */
 export const GENERATED_NOTE = "**Generated fixtures.** Where no fixture was written, the tool built one from the parts the package exports (or from what a custom element says about itself) and ran it only after it checked that the trigger and root behaved. A generated fixture is a guess about how the library is meant to be assembled, so a failure may come from how it was wired and not from the library. Treat generated results as lower evidence than an authored fixture. The source of each is in the `generated` folder beside this report. Copy one to `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) and edit it to make it an authored fixture.";
 
@@ -279,6 +289,7 @@ export function targetSection(planTarget, target, { generatedNote = true } = {})
   if (target.npm) {
     const n = target.npm;
     lines.push(`Installed ${code(`${n.name}@${n.version}`)} on its own${n.subpath ? ` and tested its ${code(`${n.name}/${n.subpath}`)} entry` : ""}, as ${adapterFor(n.flavor).describe(n)}.`, "");
+    if (n.companions?.length) lines.push(`Installed beside it, in the same folder: ${n.companions.map((c) => code(`${c.name}@${c.version}${c.subpath ? `/${c.subpath}` : ""}`)).join(", ")}.`, "");
   }
   for (const warning of target.warnings) lines.push(`Warning: ${warning}`, "");
   if (target.status === "failed") {
@@ -286,6 +297,7 @@ export function targetSection(planTarget, target, { generatedNote = true } = {})
   }
   if (target.npm) lines.push("**Archetypes.** A gap means the archetype wasn't tested, so it counts against coverage and never as a pass.", "", ...archetypeTable(target), "");
   if (generatedNote && target.npm && hasGenerated({ targets: [target] })) lines.push(GENERATED_NOTE, "");
+  if (generatedNote && target.npm && hasNativeTemplates({ targets: [target] })) lines.push(NATIVE_NOTE, "");
   /** @type {Set<string>} */
   const skipped = new Set();
   for (const [name, archetype] of Object.entries(target.archetypes)) {

package/src/report/single.js

@@ -2,7 +2,7 @@ import { FINDINGS_NOTE, coverageMatrix, finish, failCheckSection, notTestableLin
 
 /**
  * Render report.md for an audit. The text comes from results.json and nothing else.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderSingleReport({ plan, results }) {
   const lines = reportHeader(plan, results, "Accessibility report.");