@uniflowed/vite 0.0.0-alpha.14 → 0.0.0-alpha.16

package/internal/a11y-runtime.js

@@ -0,0 +1,234 @@
+// @noflow
+//
+// Plain JavaScript: this module is served to the browser as text, by
+// `./a11y.js`'s virtual module, before any transform has run on it.
+//
+// The accessibility audit `uf dev` runs against the page on screen.
+//
+// The second half of ubugeeei-prod/uf#511, and the half that is worth more: a
+// violation found while the component is being written is a violation somebody
+// can fix in the same minute, and one found in CI is a pull request that goes
+// red an hour later. Same engine and same rule set as
+// `expect(el).toHaveNoAxeViolations()` — `uf.config.js`'s `accessibility.axe`
+// is read once and given to both — so the two cannot disagree about what
+// "accessible" means.
+//
+// # It reports to the terminal rather than drawing an overlay
+//
+// `internal/diagnostics.js` records the decision and the reason, from #583: an
+// overlay is a rectangle drawn over the page, and a rectangle drawn over the
+// page is the last thing an *accessibility* report should be. It would cover
+// the markup it is complaining about, it would change the layout the audit
+// just measured, and it would need to be accessible itself. So a finding goes
+// down the channel that already exists, `POST /__uf/diagnostic`, and comes out
+// in the terminal beside every other thing `uf dev` has to say.
+//
+// # When it runs
+//
+// Once when the page has settled, and again after the DOM stops changing.
+// Not on every mutation: a React render is hundreds of them, and axe walks the
+// whole subtree each time. The debounce is what makes it a background job
+// rather than a stutter, and the audit is skipped outright while the tab is
+// hidden — a page nobody is looking at has nothing to report about.
+//
+// Development only. `./a11y.js` injects this module from `transformIndexHtml`,
+// which is guarded on `isProduction`, and the module is not reachable from any
+// entry a build follows.
+
+import axe from "axe-core";
+
+/**
+ * Whether the engine is mid-run, for every audit in the process.
+ *
+ * Module scope because `axe` is a singleton and holds a single-run lock of its
+ * own: asking it for a second run while one is going answers "Axe is already
+ * running" rather than a result, and a per-page flag would not see the other
+ * page's run. One engine, one lock.
+ */
+let engineBusy = false;
+
+/** Most violations one report names; the rest are counted. */
+const MAX_VIOLATIONS_REPORTED = 8;
+
+/** Longest excerpt of an element's markup a line quotes. */
+const MAX_NODE_CHARS = 100;
+
+/**
+ * Start auditing.
+ *
+ * `options` is generated by `./a11y.js` and carries the project's rule set,
+ * the endpoint to report to, and nothing a page could have chosen: everything
+ * here is decided by `uf.config.js` on the server before the module exists.
+ */
+export function start(options) {
+  const endpoint = options.endpoint;
+  // How long the DOM has to stop moving before an audit runs. Decided by
+  // `./a11y.js` and written into this module's last line rather than kept here
+  // as a constant, so there is one number rather than two — and so a test can
+  // drive the loop without waiting three quarters of a second per assertion.
+  const settleMs = options.settleMs;
+  const runOptions = axeOptions(options.axe ?? {});
+  const floor = options.axe?.minImpact ?? null;
+  let timer = null;
+  // Whether `stop` has been called. A run already in flight cannot be
+  // cancelled, but nothing after it should act as though the page is still
+  // being watched.
+  let stopped = false;
+  // What the last report said, so a re-render that changes nothing the audit
+  // cares about does not print the same block again. A page under active
+  // editing re-renders constantly; a terminal that repeats itself every time
+  // is a terminal nobody reads.
+  let reported = "";
+
+  const audit = async () => {
+    if (stopped || document.hidden) return;
+    if (engineBusy) {
+      // Not a run to skip — a run to come back for. The timer that brought us
+      // here cleared itself before calling, so returning without scheduling
+      // again loses the mutation for good: nothing is left pending, and the
+      // DOM it settled into never gets audited. Rescheduling rather than
+      // queueing a flag also means the wait is another settle, which is right
+      // — the tree may still be moving — and it is the same answer whether the
+      // engine is busy for this page or for another one.
+      schedule();
+      return;
+    }
+    engineBusy = true;
+    try {
+      const results = await axe.run(document, runOptions);
+      // The engine takes as long as it takes, and `stop` can land in the
+      // middle of it. A caller that has said it is done is not expecting one
+      // more report a second later.
+      if (stopped) return;
+      const violations = (results?.violations ?? []).filter((violation) =>
+        atOrAbove(violation.impact, floor),
+      );
+      const summary = violations.map((violation) => violation.id).join(",");
+      if (summary === reported) return;
+      reported = summary;
+      if (violations.length > 0) report(endpoint, violations);
+    } catch (error) {
+      // An audit that throws is a bug in this file or in the engine, and it
+      // must not take the page with it: `uf dev` is for developing the
+      // application, not this. Reported once, at `info`, and then the run is
+      // over — `reported` is left as it was so the next settle tries again.
+      report(endpoint, null, error);
+    } finally {
+      engineBusy = false;
+    }
+  };
+
+  const schedule = () => {
+    if (timer != null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void audit();
+    }, settleMs);
+  };
+
+  const observer = new MutationObserver(schedule);
+  observer.observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+  });
+  document.addEventListener("visibilitychange", () => {
+    if (!document.hidden) schedule();
+  });
+  schedule();
+
+  // Returned so a caller that owns the page's lifetime can end the loop. The
+  // generated call in `./a11y.js` ignores it: a dev server's page is over when
+  // the document is, and nothing outlives that.
+  return () => {
+    stopped = true;
+    if (timer != null) clearTimeout(timer);
+    observer.disconnect();
+  };
+}
+
+/** The project's rule set in axe's own vocabulary. */
+function axeOptions(settings) {
+  const options = {};
+  const tags = settings.tags ?? [];
+  if (tags.length > 0) options.runOnly = { type: "tag", values: [...tags] };
+  const disabled = settings.disabledRules ?? [];
+  if (disabled.length > 0) {
+    const rules = {};
+    for (const rule of disabled) rules[rule] = { enabled: false };
+    options.rules = rules;
+  }
+  return options;
+}
+
+/** Impacts weakest first, so a floor is a comparison rather than a match. */
+const IMPACTS = ["minor", "moderate", "serious", "critical"];
+
+/**
+ * Whether a violation clears the configured floor.
+ *
+ * A violation axe could not rate clears every floor: "we do not know how bad
+ * this is" is not a reason to hide it.
+ */
+function atOrAbove(impact, floor) {
+  if (floor == null || impact == null) return true;
+  const at = IMPACTS.indexOf(impact);
+  return at === -1 || at >= IMPACTS.indexOf(floor);
+}
+
+/** One element, short enough to be one line of a terminal. */
+function excerpt(html) {
+  const line = String(html ?? "")
+    .split("\n")[0]
+    .trim();
+  return line.length > MAX_NODE_CHARS ? `${line.slice(0, MAX_NODE_CHARS)}…` : line;
+}
+
+/**
+ * Send one report down the diagnostic channel.
+ *
+ * `keepalive` and a swallowed failure, because this is telemetry about the
+ * page rather than part of it: a dev server that has gone away must not turn
+ * into an unhandled rejection in the application being developed.
+ */
+function report(endpoint, violations, error) {
+  const body =
+    violations == null
+      ? {
+          severity: "info",
+          message: `the accessibility audit could not run: ${String(error)}`,
+        }
+      : {
+          severity: "warn",
+          message: `${violations.length} accessibility ${
+            violations.length === 1 ? "violation" : "violations"
+          } on this page`,
+          detail: detailLines(violations),
+        };
+  void fetch(endpoint, {
+    method: "POST",
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ ...body, url: window.location.href }),
+  }).then(
+    () => {},
+    () => {},
+  );
+}
+
+/** One line per rule, then the elements that broke it. */
+function detailLines(violations) {
+  const lines = [];
+  for (const violation of violations.slice(0, MAX_VIOLATIONS_REPORTED)) {
+    const impact = violation.impact == null ? "" : ` (${violation.impact})`;
+    lines.push(`${violation.id}${impact} — ${violation.help}`);
+    for (const node of (violation.nodes ?? []).slice(0, 2)) {
+      lines.push(`  ${excerpt(node.html)}`);
+    }
+    if (violation.helpUrl) lines.push(`  ${violation.helpUrl}`);
+  }
+  if (violations.length > MAX_VIOLATIONS_REPORTED) {
+    lines.push(`…and ${violations.length - MAX_VIOLATIONS_REPORTED} more rules`);
+  }
+  return lines;
+}

package/internal/a11y.js

@@ -0,0 +1,100 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// Serving `./a11y-runtime.js` to the page `uf dev` renders.
+//
+// The same shape as `./refresh.js`, and deliberately so: a virtual module
+// whose source is a file read from disk, and a tag added to every development
+// document that imports it. Two mechanisms for "a module uf injects into the
+// page" would be two things to keep working.
+//
+// What is different is the gate. Fast Refresh is always there; this is not.
+// axe-core is an *optional* dependency — uf does not make a project that never
+// audits carry a megabyte of rule definitions — so the injection is decided by
+// asking the project's own `node_modules` whether the engine is installed. The
+// question is answered on the server, once, before anything is injected, which
+// is why a project without the engine gets no script, no failed import and no
+// error in a console it did not open.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { DIAGNOSTIC_ENDPOINT } from "./diagnostics.js";
+
+/** Public URL the audit runtime is served from. */
+export const AUDIT_PUBLIC_PATH = "/@uf-a11y";
+
+/** The resolved id Vite hands back for it. */
+export const AUDIT_RESOLVED_ID = "\0uf:a11y-audit";
+
+const RUNTIME_SOURCE_PATH = fileURLToPath(new URL("./a11y-runtime.js", import.meta.url));
+
+/**
+ * How long the DOM has to stop moving before an audit runs, in milliseconds.
+ *
+ * A React render is hundreds of mutations and axe walks the whole subtree, so
+ * without a window this would be a stutter rather than a background job. Long
+ * enough to sit out a render and short enough that somebody who has just saved
+ * a file hears about it while they are still looking at the page.
+ */
+export const SETTLE_MS = 750;
+
+/**
+ * Whether the project has axe-core.
+ *
+ * Resolved from the project root rather than from this package, because the
+ * dependency is the *project's* — `@uniflowed/vite` declares it as an optional
+ * peer, so it is installed beside the application and not beside the plugin.
+ *
+ * A failure to resolve is the ordinary answer, not an error: "no engine" is
+ * what most projects will say, and it is the reason this function exists.
+ */
+export function auditAvailable(root) {
+  try {
+    createRequire(path.join(root, "package.json")).resolve("axe-core");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The audit module's source, with the project's settings written into its
+ * last line.
+ *
+ * Generated rather than passed at runtime because the module is a *module*:
+ * there is nowhere for a caller to hand it arguments, and a global would be a
+ * second name to agree on. `JSON.stringify` of a value uf built from its own
+ * config — never from anything a page said — is what goes in.
+ */
+export function auditRuntimeSource(settings) {
+  const options = {
+    endpoint: DIAGNOSTIC_ENDPOINT,
+    settleMs: SETTLE_MS,
+    axe: {
+      tags: settings?.tags ?? [],
+      disabledRules: settings?.disabledRules ?? [],
+      minImpact: settings?.minImpact ?? null,
+    },
+  };
+  return `${readFileSync(RUNTIME_SOURCE_PATH, "utf8")}\nstart(${JSON.stringify(options)});\n`;
+}
+
+/**
+ * The tag that loads it, or `null` when this project has no engine.
+ *
+ * `injectTo: "body"` rather than the head: the audit reads the rendered tree,
+ * so there is nothing for it to do until there is one, and a script in the
+ * head would only sit through the same wait with the parser stopped behind it.
+ */
+export function auditTag(base, available) {
+  if (!available) return null;
+  return {
+    tag: "script",
+    attrs: { type: "module", src: `${base}${AUDIT_PUBLIC_PATH.slice(1)}` },
+    injectTo: "body",
+  };
+}