@avi2dg/checks 0.34.0 → 0.35.0

package/src/quality/browser/layout.ts

@@ -0,0 +1,208 @@
+import { Effect } from "effect";
+import type { CDPSession } from "playwright-core";
+import type { Target } from "./declaration.ts";
+import { callOn, evaluate, isWithin, lineRects, nodeAt, overlapArea, querySelectorAll, readDom, viewportOf, type Dom, type Rect, type Viewport } from "./dom.ts";
+import { attempt } from "./page.ts";
+
+const EDGE_TOLERANCE_PX = 0.5;
+const OVERLAP_TOLERANCE_PX2 = 1;
+const LABEL_CHARS = 48;
+
+type Scanned = {
+  readonly name: string;
+  readonly text: string;
+  readonly lines: number;
+};
+
+type LayoutReport = {
+  readonly found: readonly string[];
+  readonly scanned: readonly Scanned[];
+  readonly parked: readonly string[];
+};
+
+type Resolved = {
+  readonly id: number;
+  readonly name: string;
+  readonly text: string;
+};
+
+function normaliseText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function label(element: Resolved): string {
+  return `${element.name} "${element.text.slice(0, LABEL_CHARS)}"`;
+}
+
+const textOf = Effect.fn("textOf")(function* (dom: Dom, id: number) {
+  const text = yield* callOn(dom, id, "function () { return this.textContent ?? ''; }");
+  return typeof text === "string" ? normaliseText(text) : "";
+});
+
+const IS_VISIBLE = `function () {
+  const box = this.getBoundingClientRect();
+  return box.width > 0 && box.height > 0 && this.checkVisibility({ visibilityProperty: true });
+}`;
+
+const IS_PARKED = `function () {
+  const box = this.getBoundingClientRect();
+  return box.right + scrollX <= 0 || box.bottom + scrollY <= 0 || box.width <= 1 || box.height <= 1;
+}`;
+
+const parkedUntilFocused = Effect.fn("parkedUntilFocused")(function* (dom: Dom, id: number) {
+  if ((yield* callOn(dom, id, IS_PARKED)) !== true) return false;
+  yield* callOn(dom, id, "function () { this.focus(); }");
+  const parkedWhenFocused = yield* callOn(dom, id, IS_PARKED);
+  yield* evaluate(dom.cdp, "document.activeElement?.blur()");
+  return parkedWhenFocused !== true;
+});
+
+const resolveTargets = Effect.fn("resolveTargets")(function* (dom: Dom, targets: readonly Target[]) {
+  const resolved = new Map<number, Resolved>();
+  const parked: string[] = [];
+  for (const target of targets) {
+    for (const id of yield* querySelectorAll(dom, target.selector)) {
+      if (resolved.has(id) || (yield* callOn(dom, id, IS_VISIBLE)) !== true) continue;
+      if (target.focusable === true && (yield* parkedUntilFocused(dom, id))) {
+        parked.push(target.name);
+        continue;
+      }
+      resolved.set(id, { id, name: target.name, text: yield* textOf(dom, id) });
+    }
+  }
+  return { elements: [...resolved.values()], parked };
+});
+
+const findOverlaps = Effect.fn("findOverlaps")(function* (dom: Dom, elements: readonly Resolved[], found: string[]) {
+  const boxes = yield* Effect.forEach(elements, (element) => lineRects(dom, element.id).pipe(Effect.map((rects) => ({ element, rects }))));
+  for (const [index, a] of boxes.entries()) {
+    for (const b of boxes.slice(index + 1)) {
+      if (isWithin(dom, a.element.id, b.element.id) || isWithin(dom, b.element.id, a.element.id)) continue;
+      const area = a.rects.reduce((sum, ra) => sum + b.rects.reduce((inner, rb) => inner + overlapArea(ra, rb), 0), 0);
+      if (area > OVERLAP_TOLERANCE_PX2) found.push(`${label(a.element)} overlaps ${label(b.element)} by ${area.toFixed(0)}px²`);
+    }
+  }
+});
+
+function probePoints(rect: Rect, viewport: Viewport): readonly (readonly [number, number])[] {
+  const y = (Math.max(rect.top, 0) + Math.min(rect.bottom, viewport.height)) / 2;
+  const inset = Math.min(2, (rect.right - rect.left) / 2);
+  return [
+    [rect.left + inset, y],
+    [(rect.left + rect.right) / 2, y],
+    [rect.right - inset, y],
+  ];
+}
+
+const judgeLine = Effect.fn("judgeLine")(function* (dom: Dom, viewport: Viewport, element: Resolved, rect: Rect) {
+  if (rect.left < -EDGE_TOLERANCE_PX || rect.right > viewport.width + EDGE_TOLERANCE_PX) {
+    return [`${label(element)} spans ${rect.left.toFixed(0)} to ${rect.right.toFixed(0)}px, past the ${viewport.width}px viewport`];
+  }
+  for (const [x, y] of probePoints(rect, viewport)) {
+    if (y < 0 || y >= viewport.height) continue;
+    const hit = yield* nodeAt(dom, viewport, x, y);
+    if (!isWithin(dom, hit, element.id)) return [`${label(element)} is covered or clipped at ${x.toFixed(0)},${y.toFixed(0)}`];
+  }
+  return [];
+});
+
+const CLIPS_ITS_OWN_TEXT = `function () {
+  if (getComputedStyle(this).display === "inline") return false;
+  return this.scrollWidth > this.clientWidth + 1 || this.scrollHeight > this.clientHeight + 1;
+}`;
+
+const FIRST_UNSHOWN_TEXT = `function () {
+  const alphaOf = (color) => {
+    const afterSlash = /\\/\\s*([^\\s)]+)\\s*\\)$/.exec(color);
+    if (afterSlash !== null) return parseFloat(afterSlash[1]);
+    const components = color.slice(color.indexOf("(") + 1, -1).split(",");
+    return components.length === 4 ? parseFloat(components[3]) : 1;
+  };
+  const unrendered = (element) =>
+    element.tagName === "TEXTAREA" ||
+    element.closest("svg title, svg desc") !== null ||
+    (!element.checkVisibility() && getComputedStyle(element).display !== "contents");
+  if (unrendered(this)) return null;
+  const walker = document.createTreeWalker(this, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, (node) => {
+    if (node.nodeType === Node.TEXT_NODE) return NodeFilter.FILTER_ACCEPT;
+    return unrendered(node) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_SKIP;
+  });
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const text = node.textContent.trim();
+    if (text === "") continue;
+    const parent = node.parentElement;
+    const style = getComputedStyle(parent);
+    let boxed = parent;
+    while (getComputedStyle(boxed).display === "contents" && boxed.parentElement !== null) boxed = boxed.parentElement;
+    const range = document.createRange();
+    range.selectNodeContents(node);
+    const drawn = Array.from(range.getClientRects()).some((rect) => rect.width > 0 && rect.height > 0);
+    const shown =
+      drawn &&
+      parseFloat(style.fontSize) > 0 &&
+      style.visibility === "visible" &&
+      boxed.checkVisibility({ checkOpacity: true }) &&
+      alphaOf(style.color) !== 0;
+    if (!shown) return text;
+  }
+  return null;
+}`;
+
+const CUT_OFF_BY_UNSCROLLABLE = `function () {
+  const unscrollable = (overflow) => overflow === "hidden" || overflow === "clip";
+  const clippers = [];
+  for (let at = this.parentElement; at !== null; at = at.parentElement) {
+    const style = getComputedStyle(at);
+    const x = unscrollable(style.overflowX);
+    const y = unscrollable(style.overflowY);
+    if (!x && !y) continue;
+    at.scrollLeft = 0;
+    at.scrollTop = 0;
+    clippers.push({ at, x, y });
+  }
+  const lines = Array.from(this.getClientRects()).filter((rect) => rect.width > 0 && rect.height > 0);
+  return clippers.some(({ at, x, y }) => {
+    const box = at.getBoundingClientRect();
+    const left = box.left + at.clientLeft;
+    const top = box.top + at.clientTop;
+    return lines.some(
+      (rect) =>
+        (x && (rect.left < left - ${EDGE_TOLERANCE_PX} || rect.right > left + at.clientWidth + ${EDGE_TOLERANCE_PX})) ||
+        (y && (rect.top < top - ${EDGE_TOLERANCE_PX} || rect.bottom > top + at.clientHeight + ${EDGE_TOLERANCE_PX})),
+    );
+  });
+}`;
+
+const judgeReach = Effect.fn("judgeReach")(function* (dom: Dom, element: Resolved, found: string[]) {
+  const unshown = yield* callOn(dom, element.id, FIRST_UNSHOWN_TEXT);
+  if (typeof unshown === "string") {
+    found.push(`${label(element)} hides its text "${normaliseText(unshown).slice(0, LABEL_CHARS)}"`);
+    return 0;
+  }
+  yield* evaluate(dom.cdp, "window.scrollTo(0, 0)");
+  if ((yield* callOn(dom, element.id, CUT_OFF_BY_UNSCROLLABLE)) === true) found.push(`${label(element)} is cut off by a container that cannot be scrolled`);
+  yield* attempt("cannot scroll an element into view", () => dom.cdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: element.id }));
+  const viewport = yield* viewportOf(dom.cdp);
+  if (viewport.scrollX > 0) found.push(`${label(element)} is reachable only by scrolling the page sideways`);
+  const rects = yield* lineRects(dom, element.id);
+  for (const rect of rects) found.push(...(yield* judgeLine(dom, viewport, element, rect)));
+  if ((yield* callOn(dom, element.id, CLIPS_ITS_OWN_TEXT)) === true) found.push(`${label(element)} clips its own text`);
+  return rects.length;
+});
+
+export const judgeLayout = Effect.fn("judgeLayout")(function* (cdp: CDPSession, targets: readonly Target[]) {
+  const found: string[] = [];
+  const viewport = yield* viewportOf(cdp);
+  if (viewport.contentWidth > viewport.width + EDGE_TOLERANCE_PX) {
+    found.push(`the page is ${viewport.contentWidth}px wide in a ${viewport.width}px viewport`);
+  }
+  const dom = yield* readDom(cdp);
+  const { elements, parked } = yield* resolveTargets(dom, targets);
+  yield* findOverlaps(dom, elements, found);
+  const scanned: Scanned[] = [];
+  for (const element of elements) {
+    const lines = yield* judgeReach(dom, element, found);
+    scanned.push({ name: element.name, text: element.text, lines });
+  }
+  return { found, scanned, parked } satisfies LayoutReport;
+});

package/src/quality/browser/motion.ts

@@ -0,0 +1,85 @@
+import { Effect, Schema } from "effect";
+import type { BrowserContext, Page } from "playwright-core";
+import { attempt, BrowserFailure } from "./page.ts";
+
+const CONTROLS = "a[href], button, summary, input, select, textarea";
+
+const HOVER_TIMEOUT_MS = 2_000;
+
+// A motion reset for reduced motion shortens animations to near zero rather than removing them, so one that ends within a frame never moves.
+const FRAME_MS = 1000 / 60;
+
+const MOTION_RECORDER = `(() => {
+  const seen = new WeakSet();
+  const started = [];
+  const scan = () => {
+    for (const animation of document.getAnimations()) {
+      if (seen.has(animation)) continue;
+      seen.add(animation);
+      if ((animation.effect?.getComputedTiming().activeDuration ?? 0) <= ${FRAME_MS}) continue;
+      started.push(animation.animationName ?? animation.transitionProperty ?? "a scripted animation");
+    }
+  };
+  const everyFrame = () => {
+    scan();
+    requestAnimationFrame(everyFrame);
+  };
+  requestAnimationFrame(everyFrame);
+  window.__takeStartedAnimations = () => {
+    scan();
+    return started.splice(0);
+  };
+})()`;
+
+const decodeStarted = Schema.decodeUnknownEffect(Schema.Array(Schema.String));
+
+export function recordMotion(context: BrowserContext): Promise<unknown> {
+  return context.addInitScript(MOTION_RECORDER);
+}
+
+const takeStartedAnimations = Effect.fn("takeStartedAnimations")(function* (page: Page) {
+  const started: unknown = yield* attempt("cannot read the motion recorder", () => page.evaluate("window.__takeStartedAnimations()"));
+  return yield* decodeStarted(started).pipe(
+    Effect.mapError(() => new BrowserFailure({ message: `the motion recorder gave ${String(started)}, so it did not run before the page opened` })),
+  );
+});
+
+type StillnessReport = {
+  readonly found: readonly string[];
+  readonly controls: number;
+  readonly unhovered: number;
+};
+
+export const judgeStillness = Effect.fn("judgeStillness")(function* (page: Page) {
+  const found: string[] = [];
+  const animatedDuring = Effect.fn("animatedDuring")(function* (moment: string) {
+    const started = yield* takeStartedAnimations(page);
+    if (started.length > 0) found.push(`${started.join(", ")} animated ${moment}`);
+  });
+  yield* animatedDuring("during load");
+  const scrollBehavior: unknown = yield* attempt("cannot read the scroll behaviour", () => page.evaluate("getComputedStyle(document.documentElement).scrollBehavior"));
+  if (scrollBehavior === "smooth") found.push("the page scrolls smoothly");
+  const controls = page.locator(CONTROLS);
+  const count = yield* attempt("cannot count the controls", () => controls.count());
+  let judged = 0;
+  let unhovered = 0;
+  for (let index = 0; index < count; index += 1) {
+    const control = controls.nth(index);
+    if (!(yield* attempt(`cannot see control ${index + 1}`, () => control.isVisible()))) continue;
+    judged += 1;
+    const hovered = yield* attempt(`cannot hover control ${index + 1}`, () => control.hover({ timeout: HOVER_TIMEOUT_MS })).pipe(
+      Effect.as(true),
+      Effect.catchTag("BrowserFailure", () => Effect.succeed(false)),
+    );
+    if (hovered) {
+      yield* animatedDuring(`on hovering control ${index + 1}`);
+      yield* attempt("cannot move the pointer away", () => page.mouse.move(0, 0));
+      yield* animatedDuring(`on leaving control ${index + 1}`);
+    } else {
+      unhovered += 1;
+    }
+    yield* attempt(`cannot focus control ${index + 1}`, () => control.focus());
+    yield* animatedDuring(`on focusing control ${index + 1}`);
+  }
+  return { found, controls: judged, unhovered } satisfies StillnessReport;
+});

package/src/quality/browser/nesting.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import { attempt } from "./page.ts";
+
+const CONTENT_MODEL = "element-permitted-content";
+
+type NestingReport = {
+  readonly found: readonly string[];
+  readonly elements: number;
+};
+
+// The rendered DOM rather than the served file, so markup a script builds is judged too.
+export const judgeNesting = Effect.fn("judgeNesting")(function* (page: Page) {
+  const { HtmlValidate } = yield* attempt("cannot load html-validate, which a product that runs the nesting check installs beside the kit", () =>
+    import("html-validate"),
+  );
+  const html = yield* attempt("cannot read the rendered page", () => page.content());
+  const elements = yield* attempt("cannot count the elements", () => page.locator("*").count());
+  const validator = new HtmlValidate({ rules: { [CONTENT_MODEL]: "error" } });
+  const { results } = yield* attempt("html-validate cannot judge the page", () => validator.validateString(html));
+  const found = results.flatMap(({ messages }) => messages.map(({ line, column, message }) => `${message} at ${line}:${column} of the rendered page`));
+  return { found, elements } satisfies NestingReport;
+});

package/src/quality/browser/page.ts

@@ -0,0 +1,66 @@
+import { Config, Effect, Schema } from "effect";
+import type { Browser, BrowserContext, CDPSession, Page } from "playwright-core";
+import type { Visit } from "./declaration.ts";
+
+export class BrowserFailure extends Schema.TaggedError<BrowserFailure>()("BrowserFailure", {
+  message: Schema.String,
+}) {}
+
+export const attempt = <A>(doing: string, run: () => Promise<A>): Effect.Effect<A, BrowserFailure> =>
+  Effect.tryPromise({
+    try: run,
+    catch: (cause) => new BrowserFailure({ message: `${doing}: ${cause instanceof Error ? cause.message : String(cause)}` }),
+  });
+
+// Playwright's own Chromium build is a separate download, so the runner drives the Chrome the machine already has.
+export const launchChrome = Effect.gen(function* () {
+  const { chromium } = yield* attempt("cannot load playwright-core, which a product that runs the browser checks installs beside the kit", () =>
+    import("playwright-core"),
+  );
+  const executablePath = yield* Config.String("CHROME_PATH").pipe(Config.withDefault(""));
+  return yield* Effect.acquireRelease(
+    attempt("cannot launch Chrome, so set CHROME_PATH to its executable", () =>
+      chromium.launch(executablePath === "" ? { channel: "chrome" } : { executablePath }),
+    ),
+    (browser) => attempt("closing Chrome", () => browser.close()).pipe(Effect.catchTag("BrowserFailure", () => Effect.void)),
+  );
+});
+
+type Opened = {
+  readonly context: BrowserContext;
+  readonly page: Page;
+  readonly cdp: CDPSession;
+};
+
+export type Preparation = (context: BrowserContext) => Promise<unknown>;
+
+const NO_PREPARATION: Preparation = () => Promise.resolve();
+
+export const openVisit = Effect.fn("openVisit")(function* (browser: Browser, { viewport, state }: Visit, prepare: Preparation = NO_PREPARATION) {
+  const touch = viewport.touch === true;
+  const context = yield* Effect.acquireRelease(
+    attempt("cannot open a browser context", () =>
+      browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height },
+        hasTouch: touch,
+        isMobile: touch,
+        reducedMotion: state.reducedMotion ?? "no-preference",
+      }),
+    ),
+    (opened) => attempt("closing a browser context", () => opened.close()).pipe(Effect.catchTag("BrowserFailure", () => Effect.void)),
+  );
+  yield* attempt("cannot prepare the browser context", () => prepare(context));
+  const page = yield* attempt("cannot open a page", () => context.newPage());
+  const cdp = yield* attempt("cannot open a DevTools session", () => context.newCDPSession(page));
+  yield* attempt("cannot enable the DevTools page domain", () => cdp.send("Page.enable"));
+  if (state.textPx !== undefined) {
+    const standard = state.textPx;
+    yield* attempt("cannot enlarge the text", () => cdp.send("Page.setFontSizes", { fontSizes: { standard } }));
+  }
+  return { context, page, cdp } satisfies Opened;
+});
+
+export const load = Effect.fn("load")(function* (page: Page, url: string) {
+  yield* attempt(`cannot load ${url}`, () => page.goto(url, { waitUntil: "load" }));
+  yield* attempt(`fonts never settle on ${url}`, () => page.evaluate("document.fonts.ready.then(() => undefined)"));
+});

package/src/quality/browser/report.ts

@@ -0,0 +1,48 @@
+import { describeVisit, type Declaration, type Visit } from "./declaration.ts";
+
+export const NAME = "browser";
+
+export type Run = {
+  readonly check: string;
+  readonly visit: Visit;
+  readonly inventory: readonly string[];
+  readonly found: readonly string[];
+  readonly unverified: readonly string[];
+};
+
+export type Outcome = {
+  readonly runs: readonly Run[];
+  readonly missingRoutes: readonly string[];
+};
+
+export function counted(names: readonly string[]): readonly string[] {
+  const counts = new Map<string, number>();
+  for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+  return [...counts].map(([name, count]) => `${name} ${count}`);
+}
+
+function failuresOf({ runs, missingRoutes }: Outcome): readonly string[] {
+  return [
+    ...missingRoutes.map((path) => `route ${path} serves no page from the declared site`),
+    ...(runs.length === 0 ? ["the declaration leaves no check to run"] : []),
+    ...runs.flatMap(({ check, visit, found }) => found.map((one) => `${check} at ${describeVisit(visit)}: ${one}`)),
+  ];
+}
+
+export function passes(outcome: Outcome): boolean {
+  return failuresOf(outcome).length === 0;
+}
+
+export function report(declaration: Declaration, outcome: Outcome): string {
+  const failures = failuresOf(outcome);
+  const unverified = outcome.runs.flatMap(({ check, visit, unverified: some }) => some.map((one) => `${check} at ${describeVisit(visit)}: ${one}`));
+  const scope = [
+    `${outcome.runs.length} check run(s) over ${declaration.routes.length} route(s), ${declaration.viewports.length} viewport(s),`,
+    `${declaration.states.length} state(s) and ${declaration.targets.length} target(s)`,
+  ].join(" ");
+  return [
+    ...outcome.runs.map(({ check, visit, inventory }) => `${NAME}: ${check} at ${describeVisit(visit)} scanned ${inventory.length === 0 ? "nothing" : inventory.join(", ")}`),
+    ...(unverified.length === 0 ? [] : [`${NAME}: ${unverified.length} contrast check(s) axe cannot measure, reported as unverified:`, ...unverified.map((one) => `  ${one}`)]),
+    ...(failures.length === 0 ? [`${NAME}: ${scope} pass`] : [`${NAME}: ${failures.length} failure(s) in ${scope}:`, ...failures.map((one) => `  ${one}`)]),
+  ].join("\n");
+}

package/src/quality/browser/serve.ts

@@ -0,0 +1,48 @@
+import { Effect, FileSystem, Path } from "effect";
+import { Usage } from "../../core/main.ts";
+
+const INDEX = "index.html";
+
+export type Site = {
+  readonly files: ReadonlyMap<string, string>;
+};
+
+export const readSite = Effect.fn("readSite")(function* (root: string, site: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = path.resolve(root, site);
+  const isDirectory = yield* fs.stat(dir).pipe(
+    Effect.map(({ type }) => type === "Directory"),
+    Effect.orElseSucceed(() => false),
+  );
+  if (!isDirectory) return yield* new Usage({ message: `the declared site ${site} is not a directory, so build the site before the browser checks run` });
+  const files = new Map<string, string>();
+  for (const entry of yield* fs.readDirectory(dir, { recursive: true })) {
+    const file = path.join(dir, entry);
+    if ((yield* fs.stat(file)).type !== "File") continue;
+    const url = `/${entry.split(path.sep).join("/")}`;
+    files.set(url, file);
+    if (url.endsWith(`/${INDEX}`)) files.set(url.slice(0, -INDEX.length), file);
+  }
+  return { files } satisfies Site;
+});
+
+function answer(site: Site, request: Request): Response {
+  const url = new URL(request.url);
+  const pathname = decodeURIComponent(url.pathname);
+  const file = site.files.get(pathname);
+  if (file !== undefined) return new Response(Bun.file(file));
+  if (site.files.has(`${pathname}/`)) {
+    url.pathname = `${url.pathname}/`;
+    return Response.redirect(url.href, 301);
+  }
+  return new Response("not found", { status: 404 });
+}
+
+export const serveSite = Effect.fn("serveSite")(function* (site: Site) {
+  const server = yield* Effect.acquireRelease(
+    Effect.sync(() => Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: (request) => answer(site, request) })),
+    (served) => Effect.promise(() => served.stop()),
+  );
+  return `http://127.0.0.1:${server.port}/`;
+});

package/src/quality/browser/targets.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import type { Target } from "./declaration.ts";
+import { attempt, type BrowserFailure } from "./page.ts";
+
+type TargetsReport = {
+  readonly found: readonly string[];
+  readonly visible: ReadonlyMap<string, number>;
+};
+
+export const countVisible = (page: Page, selector: string): Effect.Effect<number, BrowserFailure> =>
+  attempt(`cannot query ${selector}`, () => page.locator(selector).filter({ visible: true }).count());
+
+export const judgeTargets = Effect.fn("judgeTargets")(function* (page: Page, targets: readonly Target[]) {
+  const found: string[] = [];
+  const visible = new Map<string, number>();
+  for (const target of targets) {
+    const shown = yield* countVisible(page, target.selector);
+    visible.set(target.name, shown);
+    if (shown === 0) found.push(`${target.name} (${target.selector}) matches no visible element`);
+  }
+  return { found, visible } satisfies TargetsReport;
+});

package/src/quality/frontend-syntax.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env bun
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import type { LintResult } from "stylelint";
+import { runMain, Usage } from "../core/main.ts";
+
+const NAME = "frontend-syntax";
+
+const DECLARATION = "frontend-syntax.json";
+
+const TRANSITION_ALL = "declaration-property-value-disallowed-list";
+const BODY_WIDE_USER_SELECT = "rule-selector-property-disallowed-list";
+const UNPARSED = "CssSyntaxError";
+
+const RULES = {
+  [TRANSITION_ALL]: [{ "/^(?:-[a-z]+-)?transition(?:-property)?$/": ["/(?:^|[\\s,])all(?:[\\s,]|$)/i"] }],
+  [BODY_WIDE_USER_SELECT]: [{ "/(?:^|,)\\s*(?:html|body|:root|\\*|:global\\(\\s*(?:html|body|:root|\\*)\\s*\\))\\s*(?:,|$)/": ["/^(?:-[a-z]+-)?user-select$/"] }],
+} as const;
+
+const ADVICE: Readonly<Record<string, string>> = {
+  [TRANSITION_ALL]: "Name the properties the transition animates.",
+  [BODY_WIDE_USER_SELECT]: "Leave text selectable across the page, and turn selection off only on the control that needs it.",
+  [UNPARSED]: "The gate judges only what parses.",
+};
+
+const MARKUP = ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
+
+const Declaration = Schema.Struct({ inputs: Schema.NonEmptyArray(Schema.NonEmptyString) });
+
+const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  readonly text: string;
+};
+
+export type Input = {
+  readonly glob: string;
+  readonly files: readonly string[];
+};
+
+export type Scan = {
+  readonly inputs: readonly Input[];
+  readonly violations: readonly Violation[];
+};
+
+class FrontendSyntaxError extends Schema.TaggedError<FrontendSyntaxError>()("FrontendSyntaxError", {
+  message: Schema.String,
+}) {}
+
+class NoFilesFound extends Schema.TaggedError<NoFilesFound>()("NoFilesFound", {}) {}
+
+function isNoFilesFound(cause: unknown): boolean {
+  return cause instanceof Error && cause.name === "NoFilesFoundError";
+}
+
+const loadPeer = <A>(name: string, load: () => Promise<A>) =>
+  Effect.tryPromise({
+    try: load,
+    catch: () =>
+      new Usage({ message: `cannot load ${name}, which a repository that declares ${DECLARATION} installs beside the kit as an optional peer` }),
+  });
+
+const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const file = (yield* Path.Path).join(root, DECLARATION);
+  if (!(yield* fs.exists(file))) {
+    return yield* new Usage({ message: `${DECLARATION} is missing, and a repository opts in to this gate by declaring its inputs there` });
+  }
+  return yield* decodeDeclaration(yield* fs.readFileString(file)).pipe(
+    Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
+  );
+});
+
+function violationsOf(result: LintResult, relative: (file: string) => string): readonly Violation[] {
+  const file = relative(result.source ?? "");
+  return result.warnings.map(({ line, column, rule, text }) => ({
+    file,
+    line,
+    column,
+    text: `${text.replace(` (${rule})`, "")}. ${ADVICE[rule] ?? ""}`.trim(),
+  }));
+}
+
+export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs: readonly string[]) {
+  const path = yield* Path.Path;
+  const stylelint = (yield* loadPeer("stylelint", () => import("stylelint"))).default;
+  const html = (yield* loadPeer("postcss-html", () => import("postcss-html"))).default;
+  const config = { rules: RULES, overrides: [{ files: MARKUP, customSyntax: html }] };
+  const relative = (file: string): string => path.relative(root, file);
+  const inputs: Input[] = [];
+  const violations = new Map<string, Violation>();
+  for (const glob of globs) {
+    const linted: readonly LintResult[] = yield* Effect.tryPromise({
+      try: () => stylelint.lint({ files: glob, cwd: root, config }),
+      catch: (cause) => (isNoFilesFound(cause) ? new NoFilesFound() : new FrontendSyntaxError({ message: `stylelint fails on ${glob}: ${String(cause)}` })),
+    }).pipe(
+      Effect.map(({ results }) => results),
+      Effect.catchTag("NoFilesFound", () => Effect.succeed([])),
+    );
+    const results = linted.filter(({ ignored }) => ignored !== true);
+    const invalid = results.flatMap(({ invalidOptionWarnings }) => invalidOptionWarnings.map(({ text }) => text));
+    if (invalid.length > 0) return yield* new FrontendSyntaxError({ message: `stylelint refuses the kit's rule options: ${invalid.join("; ")}` });
+    inputs.push({ glob, files: results.map((result) => relative(result.source ?? "")).toSorted() });
+    for (const violation of results.flatMap((result) => violationsOf(result, relative))) {
+      violations.set(`${violation.file}:${violation.line}:${violation.column}:${violation.text}`, violation);
+    }
+  }
+  const byPlace = (a: Violation, b: Violation): number => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column;
+  return { inputs, violations: [...violations.values()].toSorted(byPlace) } satisfies Scan;
+});
+
+export function passes({ inputs, violations }: Scan): boolean {
+  return violations.length === 0 && inputs.every(({ files }) => files.length > 0);
+}
+
+export function report({ inputs, violations }: Scan): string {
+  const files = new Set(inputs.flatMap((input) => input.files)).size;
+  const scanned = `${files} file(s) from ${inputs.length} declared input(s)`;
+  const empty = inputs.filter((input) => input.files.length === 0);
+  if (violations.length === 0 && empty.length === 0) return `${NAME}: no violation in ${scanned}`;
+  return [
+    `${NAME}: ${violations.length + empty.length} problem(s) in ${scanned}:`,
+    ...empty.map(({ glob }) => `  ${glob}: the declared input matches no file`),
+    ...violations.map(({ file, line, column, text }) => `  ${file}:${line}:${column} ${text}`),
+  ].join("\n");
+}
+
+const gate = Effect.gen(function* () {
+  const root = (yield* Path.Path).resolve(process.argv[2] ?? ".");
+  const { inputs } = yield* readDeclaration(root);
+  const scan = yield* scanInputs(root, inputs);
+  yield* Console.log(report(scan));
+  return passes(scan);
+});
+
+if (import.meta.main) runMain(NAME, gate);

package/stryker.preset.js

@@ -1,3 +1,4 @@
+import { availableParallelism } from "node:os";
 import { fileURLToPath } from "node:url";
 import { GUARD_IGNORER } from "./src/testing/mutation-guard-plugin.js";
 import { fullRunRefusal } from "./src/testing/mutation-scope.js";
@@ -6,6 +7,8 @@ const [, , command, ...args] = process.argv;
 const refusal = command === "run" ? fullRunRefusal(args, process.env.CI ?? "") : undefined;
 if (refusal !== undefined) throw new Error(refusal);
 
+export const halfAvailableCores = (cores = availableParallelism()) => Math.max(1, Math.floor(cores / 2));
+
 export default {
   packageManager: "npm",
   plugins: [
@@ -21,6 +24,6 @@ export default {
   coverageAnalysis: "perTest",
   reporters: ["html", "json", "clear-text", "progress"],
   timeoutMS: 60000,
-  concurrency: 8,
+  concurrency: halfAvailableCores(),
   thresholds: { high: 85, low: 70, break: null },
 };