@avi2dg/checks 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -54,6 +54,8 @@
     "src/docs/prose-matchers.ts",
     "src/quality/comments.ts",
     "src/quality/comment-gate.ts",
+    "src/quality/frontend-syntax.ts",
+    "src/quality/browser/",
     "src/complexity/suppressions-ratchet.ts",
     "src/complexity/repetition.ts",
     "src/complexity/unused.ts",
@@ -95,7 +97,8 @@
     "./scripts/prose-matchers.ts": "./src/docs/prose-matchers.ts",
     "./stryker.preset.js": "./stryker.preset.js",
     "./templates/*": "./dist/templates/*",
-    "./tsconfig.effect.json": "./tsconfig.effect.json"
+    "./tsconfig.effect.json": "./tsconfig.effect.json",
+    "./browser-hooks.ts": "./src/quality/browser/hooks.ts"
   },
   "bin": {
     "checks-lint": "src/core/lint.ts",
@@ -122,7 +125,9 @@
     "checks-docs": "src/docs/docs.ts",
     "checks-vendor": "src/dependencies/vendor.ts",
     "checks-advisories": "src/dependencies/advisories.ts",
-    "checks-secrets": "src/delivery/secrets.ts"
+    "checks-secrets": "src/delivery/secrets.ts",
+    "checks-frontend-syntax": "src/quality/frontend-syntax.ts",
+    "checks-browser": "src/quality/browser/browser.ts"
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
@@ -134,16 +139,39 @@
     "mutate:incremental": "bunx stryker run --incremental"
   },
   "peerDependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "@effect/tsgo": "0.45.0",
     "@swc/core": "1.16.2",
     "dependency-cruiser": "18.4.0",
-    "@effect/tsgo": "0.45.0",
     "effect": "4.0.0",
+    "html-validate": "11.16.0",
     "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002",
+    "playwright-core": "1.63.0",
+    "postcss-html": "2.0.0",
+    "stylelint": "17.16.0",
     "typescript": "7.0.2"
   },
+  "peerDependenciesMeta": {
+    "@axe-core/playwright": {
+      "optional": true
+    },
+    "html-validate": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    },
+    "postcss-html": {
+      "optional": true
+    },
+    "stylelint": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@axe-core/playwright": "4.13.0",
     "@effect/tsgo": "0.45.0",
     "@hughescr/stryker-bun-runner": "1.4.0",
     "@oxlint/plugins": "1.83.0",
@@ -153,9 +181,13 @@
     "@types/commonmark": "0.27.10",
     "dependency-cruiser": "18.4.0",
     "effect": "4.0.0",
+    "html-validate": "11.16.0",
     "jscpd": "5.3.2",
     "oxlint": "1.83.0",
     "oxlint-tsgolint": "7.0.2002",
+    "playwright-core": "1.63.0",
+    "postcss-html": "2.0.0",
+    "stylelint": "17.16.0",
     "typescript": "7.0.2"
   },
   "dependencies": {

package/src/core/gates.ts

@@ -36,11 +36,14 @@ export const LINTED_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx", "*.a
 
 const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
 
+const FRONTEND_SYNTAX_DECLARATION: TrackedContent = { pathspecs: ["frontend-syntax.json"], content: "a frontend syntax declaration" };
+
 export const KIT_GATES = [
   { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-commit-identity", vector: "delivery", file: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-frontend-syntax", vector: "quality", file: "frontend-syntax.ts", reads: "tree", appliesTo: FRONTEND_SYNTAX_DECLARATION },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-secrets", vector: "delivery", file: "secrets.ts", reads: "range", appliesTo: EVERY_REPOSITORY },

package/src/delivery/ci-wiring.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
-import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
-import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
+import { fromProgram, invokes, mentions, plainCommand, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
 
 export type { Command };
 
@@ -34,6 +34,18 @@ export type Gap = {
   readonly blocked: readonly BlockedInvocation[];
 };
 
+export type Visibility = "private" | "public" | "unknown";
+
+export type RunnerPolicy = {
+  readonly visibility: Visibility;
+  readonly scripts: ReadonlyMap<string, string>;
+};
+
+export type RunnerFault = {
+  readonly location: string;
+  readonly fault: string;
+};
+
 type RunStep = {
   readonly location: string;
   readonly blocker: string | undefined;
@@ -58,6 +70,17 @@ const CONSTANTS = new Map([
   ["false", false],
 ]);
 const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+// GitHub expressions match context and property names without regard to case.
+const OVERRIDE_ACCESS = String.raw`vars\s*(?:\.\s*CI_RUNS_ON\b|\[\s*'CI_RUNS_ON'\s*\])`;
+const RUNNER_OVERRIDE = new RegExp(String.raw`\b${OVERRIDE_ACCESS}`, "i");
+const HOSTED_OVERRIDE = new RegExp(String.raw`^\$\{\{\s*${OVERRIDE_ACCESS}\s*\|\|\s*'ubuntu-latest'\s*\}\}$`, "i");
+const MUTATION_RUNNER = ["self-hosted", "Linux", "X64", "winbox"];
+const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
+const MUTATION_BINS = ["checks-mutation", "checks-mutation-compare"];
+const BUN_OPERANDS = new Set(["--cwd", "-c", "--config", "--env-file", "-F", "--filter", "-r", "--preload", "--require", "--import", "-e", "--eval", "-p", "--print", "--elide-lines", "--tsconfig-override"]);
+// bun's own commands take precedence over a package.json script of the same name unless bun run names it.
+const BUN_COMMANDS = new Set(["test", "repl", "exec", "install", "i", "add", "a", "remove", "rm", "update", "outdated", "link", "unlink", "pm", "build", "init", "create", "c", "upgrade", "publish", "patch", "patch-commit", "audit", "info", "why"]);
+const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -243,13 +266,75 @@ export function declarationFor(scripts: readonly string[], branch: string): Decl
   };
 }
 
+function runsMutation(script: string, scripts: ReadonlyMap<string, string>, walked: readonly string[] = []): boolean {
+  return shellCommands(script).some((command) => mutationCommand(command, scripts, walked));
+}
+
+function mutationCommand(command: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [first = "", ...rest] = fromProgram(command);
+  return first === "bun" ? bunRunsMutation(rest, scripts, walked) : mutationBin([first, ...rest]);
+}
+
+function bunRunsMutation(args: Command, scripts: ReadonlyMap<string, string>, walked: readonly string[]): boolean {
+  const [command = "", ...rest] = withoutOptions(args, BUN_OPERANDS);
+  if (command === "x") return mutationCommand(["bunx", ...rest], scripts, walked);
+  if (BUN_COMMANDS.has(command)) return false;
+  const [target = "", ...targetArgs] = command === "run" ? withoutOptions(rest, BUN_OPERANDS) : [command, ...rest];
+  const body = walked.includes(target) ? undefined : scripts.get(target);
+  return body === undefined ? mutationBin([target, ...targetArgs]) : runsMutation(body, scripts, [...walked, target]);
+}
+
+function mutationBin([program = "", subcommand]: Command): boolean {
+  const bin = program.slice(program.lastIndexOf("/") + 1);
+  return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
+}
+
+function sameLabels(runsOn: unknown, labels: readonly string[]): boolean {
+  const named = Array.isArray(runsOn) ? names(runsOn) : undefined;
+  return named?.length === labels.length && labels.every((label) => named.includes(label));
+}
+
+function readsOverride(runsOn: unknown): boolean {
+  if (typeof runsOn === "string") return RUNNER_OVERRIDE.test(runsOn);
+  const values = isRecord(runsOn) ? Object.values(runsOn) : Array.isArray(runsOn) ? runsOn : [];
+  return values.some(readsOverride);
+}
+
+function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility): string | undefined {
+  const overridden = readsOverride(runsOn);
+  const pin = `set runs-on: [${MUTATION_RUNNER.join(", ")}]`;
+  if (mutation && overridden) return `a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; ${pin}`;
+  if (mutation) return visibility === "private" && !sameLabels(runsOn, MUTATION_RUNNER) ? `a mutation job in a private repository runs off winbox; ${pin}` : undefined;
+  const hosted = typeof runsOn === "string" && HOSTED_OVERRIDE.test(runsOn.trim());
+  if (hosted || (visibility !== "private" && !overridden)) return undefined;
+  return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
+}
+
+export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
+  return workflows.flatMap((workflow) => {
+    const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+    if (!isRecord(jobs)) return [];
+    return Object.entries(jobs).flatMap(([id, job]) => {
+      if (!isRecord(job) || job["runs-on"] === undefined) return [];
+      const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+      const mutation = steps.some((step: unknown) => isRecord(step) && typeof step["run"] === "string" && runsMutation(step["run"], policy.scripts));
+      const fault = runnerFault(job["runs-on"], mutation, policy.visibility);
+      return fault === undefined ? [] : [{ location: `${workflow.path} job ${id}`, fault }];
+    });
+  });
+}
+
+export function formatRunnerReport(faults: readonly RunnerFault[]): string {
+  return [`ci-wiring: ${faults.length} job(s) run on the wrong runner:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}
+
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
     try: () => ({ path, document: Bun.YAML.parse(text) }),
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
-export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+const readScripts = Effect.fn("readScripts")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const file = (yield* Path.Path).join(root, "package.json");
   const { scripts = {} } = (yield* fs.exists(file))
@@ -258,7 +343,22 @@ export const readDeclaration = Effect.fn("readDeclaration")(function* (root: str
         Effect.mapError((cause) => new WiringError({ message: `cannot read ${file}: ${cause.message}` })),
       )
     : Manifest.make({});
-  return declarationFor(Object.keys(scripts), yield* defaultBranch(root));
+  return new Map(Object.entries(scripts));
+});
+
+export const readDeclaration = Effect.fn("readDeclaration")(function* (root: string) {
+  return declarationFor([...(yield* readScripts(root)).keys()], yield* defaultBranch(root));
+});
+
+// Only GitHub's event says whether the repository is private, so a run outside CI judges what holds in either.
+const readVisibility = Effect.gen(function* () {
+  const eventPath = yield* Config.String("GITHUB_EVENT_PATH").pipe(Config.withDefault(""));
+  if (eventPath === "") return "unknown" satisfies Visibility;
+  return yield* (yield* FileSystem.FileSystem).readFileString(eventPath).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(EventRepository)),
+    Effect.map(({ repository }): Visibility => (repository.private ? "private" : "public")),
+    Effect.orElseSucceed((): Visibility => "unknown"),
+  );
 });
 
 export const readWorkflows = Effect.fn("readWorkflows")(function* (root: string) {
@@ -283,7 +383,9 @@ const wiring = Effect.gen(function* () {
   const gaps = findGaps(declaration, workflows);
   const gapReport = formatReport(declaration, gaps);
   yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
-  return gaps.length === 0;
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts: yield* readScripts(root) }, workflows);
+  if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
+  return gaps.length === 0 && faults.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/shell-command.ts

@@ -64,6 +64,149 @@ export function plainCommand(script: string): Command | undefined {
   return words.length === 0 ? undefined : words;
 }
 
+type ShellPart = Span & { readonly substitutions: readonly string[] };
+
+const COMMAND_BREAKS = new Set(["\n", ";", "&", "|", "(", ")", "`"]);
+const WORD_BREAKS = new Set([" ", "\t"]);
+const REDIRECTS = new Set(["<", ">"]);
+const REDIRECT_OPERATOR = /^[<>][<>&|]*/;
+const FILE_DESCRIPTOR = /^\d+$/;
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const RESERVED_WORDS = new Set(["!", "{", "if", "then", "elif", "else", "while", "until", "do"]);
+const LAUNCHER_OPERANDS = new Map<string, ReadonlySet<string>>([
+  ["time", new Set(["-o", "-f"])],
+  ["env", new Set(["-u", "-C", "--unset", "--chdir"])],
+  ["exec", new Set(["-a"])],
+  ["nohup", new Set()],
+  ["sudo", new Set(["-u", "-g", "-C", "-D", "-h", "-p", "-r", "-t", "-U", "--user", "--group", "--chdir", "--host", "--prompt"])],
+  ["bunx", new Set(["-p", "--package"])],
+  ["npx", new Set(["-p", "--package", "-c", "--call", "-w", "--workspace"])],
+]);
+
+function substitutionEnd(script: string, start: number): number {
+  if (script.charAt(start) === "`") {
+    const close = script.indexOf("`", start + 1);
+    return close === -1 ? script.length : close;
+  }
+  let depth = 0;
+  for (let index = start + 1; index < script.length; index += 1) {
+    if (script.charAt(index) === "(") depth += 1;
+    if (script.charAt(index) === ")") depth -= 1;
+    if (depth === 0) return index;
+  }
+  return script.length;
+}
+
+function doubleQuotedPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  const next = script.charAt(index + 1);
+  if (char === "\\" && next === "\n") return { text: "", end: index + 2, substitutions: [] };
+  if (char === "\\" && DOUBLE_QUOTE_ESCAPES.has(next)) return { text: next, end: index + 2, substitutions: [] };
+  if (char !== "`" && !(char === "$" && next === "(")) return { text: char, end: index + 1, substitutions: [] };
+  const end = substitutionEnd(script, index);
+  return { text: "", end: end + 1, substitutions: [script.slice(index + (char === "`" ? 1 : 2), end)] };
+}
+
+function shellDoubleQuoted(script: string, open: number): ShellPart {
+  let text = "";
+  const substitutions: string[] = [];
+  let index = open + 1;
+  while (index < script.length && script.charAt(index) !== '"') {
+    const part = doubleQuotedPart(script, index);
+    text += part.text;
+    substitutions.push(...part.substitutions);
+    index = part.end;
+  }
+  return { text, end: index + 1, substitutions };
+}
+
+function shellPart(script: string, index: number): ShellPart {
+  const char = script.charAt(index);
+  if (char === "'") {
+    const close = script.indexOf("'", index + 1);
+    const end = close === -1 ? script.length : close;
+    return { text: script.slice(index + 1, end), end: end + 1, substitutions: [] };
+  }
+  if (char === '"') return shellDoubleQuoted(script, index);
+  if (char === "\\") return { text: script.charAt(index + 1), end: index + 2, substitutions: [] };
+  return { text: char, end: index + 1, substitutions: [] };
+}
+
+function commentEnd(script: string, from: number): number {
+  const newline = script.indexOf("\n", from);
+  return newline === -1 ? script.length : newline;
+}
+
+type ShellParse = {
+  readonly commands: string[][];
+  readonly substitutions: string[];
+  words: string[];
+  word: string | undefined;
+  redirecting: boolean;
+};
+
+function endWord(parse: ShellParse): void {
+  if (parse.word === undefined) return;
+  if (!parse.redirecting) parse.words.push(parse.word);
+  parse.redirecting = false;
+  parse.word = undefined;
+}
+
+function endCommand(parse: ShellParse): void {
+  endWord(parse);
+  parse.commands.push(parse.words);
+  parse.words = [];
+  parse.redirecting = false;
+}
+
+function startRedirect(parse: ShellParse, script: string, index: number): number {
+  if (parse.word !== undefined && FILE_DESCRIPTOR.test(parse.word)) parse.word = undefined;
+  endWord(parse);
+  parse.redirecting = true;
+  return index + (REDIRECT_OPERATOR.exec(script.slice(index))?.[0].length ?? 1);
+}
+
+export function shellCommands(script: string): readonly Command[] {
+  const parse: ShellParse = { commands: [], substitutions: [], words: [], word: undefined, redirecting: false };
+  let index = 0;
+  while (index < script.length) {
+    const char = script.charAt(index);
+    if (char === "\\" && script.charAt(index + 1) === "\n") {
+      index += 2;
+    } else if (char === "#" && parse.word === undefined) {
+      index = commentEnd(script, index);
+    } else if (REDIRECTS.has(char)) {
+      index = startRedirect(parse, script, index);
+    } else if (COMMAND_BREAKS.has(char) || WORD_BREAKS.has(char)) {
+      if (COMMAND_BREAKS.has(char)) endCommand(parse);
+      else endWord(parse);
+      index += 1;
+    } else {
+      const part = shellPart(script, index);
+      parse.word = (parse.word ?? "") + part.text;
+      parse.substitutions.push(...part.substitutions);
+      index = part.end;
+    }
+  }
+  endCommand(parse);
+  return [...parse.commands, ...parse.substitutions.flatMap(shellCommands)].filter((command) => command.length > 0);
+}
+
+export function withoutOptions(words: Command, operands: ReadonlySet<string>): Command {
+  const [first = "", ...rest] = words;
+  if (first === "--") return rest;
+  if (!first.startsWith("-")) return words;
+  return withoutOptions(operands.has(first) ? rest.slice(1) : rest, operands);
+}
+
+export function fromProgram(words: Command): Command {
+  const [first = "", ...rest] = words;
+  if (ASSIGNMENT.test(first) || RESERVED_WORDS.has(first)) return fromProgram(rest);
+  const operands = LAUNCHER_OPERANDS.get(first);
+  return operands === undefined ? words : fromProgram(withoutOptions(rest, operands));
+}
+
 // bun run resolves any other word, even one holding a slash, to a package.json script of that name first.
 const FILE_PATH = /^\.{0,2}\//;
 

package/src/docs/prose-matchers.ts

@@ -335,9 +335,9 @@ function ruleFindings(line: MarkdownLine, reader: Reader): ProseFinding[] {
   );
 }
 
-const SENTENCE_BREAK = /(?<=[^\s.!?])[.!?]["'”’)\]*_]*\s+(?=[A-Z"“*_[\0])/g;
-const ABBREVIATION = /\b(?:e\.g|i\.e|etc|vs|cf|approx|Mr|Mrs|Ms|Dr|St|No|Fig)$/i;
-const SENTENCE_END = /[.!?:]["'”’)\]*_]*\s*$/;
+const SENTENCE_BREAK = /(?<=[^\s.!?])[.!?]["'”’»)\]*_]*\s+(?=[\p{Lu}"“«*_[\0])/gu;
+const ABBREVIATION = /(?<![\p{L}\p{N}_])(?:e\.g|i\.e|etc|vs|cf|approx|Mr|Mrs|Ms|Dr|St|No|Fig|см|напр|т\.\s*[едп]|др|стр)$/iu;
+const SENTENCE_END = /[.!?:]["'”’»)\]*_]*\s*$/;
 const LIST_ITEM = /^(?:\s*>)*\s*(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
 const QUOTE_DEPTH = /^(?:\s*>)*/;
 
@@ -355,7 +355,7 @@ function secondSentence(line: MarkdownLine): ProseFinding | undefined {
   return undefined;
 }
 
-const OPENS_LOWERCASE = /^\s*[a-z]/;
+const OPENS_LOWERCASE = /^\s*\p{Ll}/u;
 
 // A sentence may end inside the code or link that closes its line, so only a lowercase next line proves it runs on.
 function endsMidSentence(line: MarkdownLine, next: MarkdownLine): boolean {

package/src/docs/sentence-length.ts

@@ -38,7 +38,7 @@ function orderedAt(raw: string): boolean {
 }
 
 function isWordChar(char: string): boolean {
-  return (char >= "0" && char <= "9") || (char >= "A" && char <= "Z") || (char >= "a" && char <= "z");
+  return /[\p{L}\p{N}]/u.test(char);
 }
 
 function wordsIn(sentence: string): number {
@@ -59,7 +59,7 @@ function wordsIn(sentence: string): number {
 }
 
 function isCloser(char: string): boolean {
-  return char === '"' || char === "'" || char === ")" || char === "]" || char === "*" || char === "_" || char === "”" || char === "’";
+  return char === '"' || char === "'" || char === ")" || char === "]" || char === "*" || char === "_" || char === "”" || char === "’" || char === "»";
 }
 
 function sentencesIn(body: string): readonly string[] {

package/src/quality/browser/assets.ts

@@ -0,0 +1,23 @@
+import type { Page } from "playwright-core";
+
+const FAILING_STATUS = 400;
+
+export type AssetWatch = {
+  readonly requested: () => number;
+  readonly found: () => readonly string[];
+};
+
+export function watchAssets(page: Page): AssetWatch {
+  const found: string[] = [];
+  let requested = 0;
+  page.on("request", () => {
+    requested += 1;
+  });
+  page.on("requestfailed", (request) => {
+    found.push(`${request.url()} fails to load: ${request.failure()?.errorText ?? "no reason given"}`);
+  });
+  page.on("response", (response) => {
+    if (response.status() >= FAILING_STATUS) found.push(`${response.url()} answers ${response.status()}`);
+  });
+  return { requested: () => requested, found: () => [...found] };
+}

package/src/quality/browser/axe.ts

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import { attempt } from "./page.ts";
+
+const WCAG_AA = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
+
+const CONTRAST = "color-contrast";
+
+type AxeReport = {
+  readonly found: readonly string[];
+  readonly unverified: readonly string[];
+  readonly rules: number;
+};
+
+type Node = { readonly target: readonly unknown[]; readonly any: readonly { readonly message: string }[] };
+
+function where(node: Node): string {
+  return node.target.map(String).join(" ");
+}
+
+export const judgeAxe = Effect.fn("judgeAxe")(function* (page: Page) {
+  const { AxeBuilder } = yield* attempt("cannot load @axe-core/playwright, which a product that runs the axe check installs beside the kit", () =>
+    import("@axe-core/playwright"),
+  );
+  const results = yield* attempt("axe cannot analyse the page", () => new AxeBuilder({ page }).withTags(WCAG_AA).analyze());
+  const found = results.violations.flatMap((violation) =>
+    violation.nodes.map((node) => `${violation.id} (${violation.impact ?? "unknown"}): ${where(node)}: ${violation.help}`),
+  );
+  const unverified = results.incomplete
+    .filter(({ id }) => id === CONTRAST)
+    .flatMap(({ nodes }) => nodes.map((node) => `${CONTRAST} unverified: ${where(node)}: ${node.any[0]?.message ?? "axe cannot measure it"}`));
+  return { found, unverified, rules: results.passes.length + results.violations.length + results.incomplete.length } satisfies AxeReport;
+});

package/src/quality/browser/browser.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+import { Console, Effect, Path } from "effect";
+import type { Browser } from "playwright-core";
+import { runMain } from "../../core/main.ts";
+import { watchAssets } from "./assets.ts";
+import { judgeAxe } from "./axe.ts";
+import { readDeclaration, targetsOn, visitsOf, type CheckName, type Declaration, type Visit } from "./declaration.ts";
+import { loadHooks, runHook, type ProductCheck } from "./hooks.ts";
+import { judgeKeyboard } from "./keyboard.ts";
+import { judgeLayout } from "./layout.ts";
+import { judgeStillness, recordMotion } from "./motion.ts";
+import { judgeNesting } from "./nesting.ts";
+import { attempt, launchChrome, load, openVisit, type BrowserFailure } from "./page.ts";
+import { counted, NAME, passes, report, type Run } from "./report.ts";
+import { readSite, serveSite } from "./serve.ts";
+import { judgeTargets } from "./targets.ts";
+
+const NO_TARGET = "scanned no target";
+
+type Visiting = {
+  readonly browser: Browser;
+  readonly declaration: Declaration;
+  readonly visit: Visit;
+  readonly url: string;
+};
+
+const run = (check: string, visit: Visit, inventory: readonly string[], found: readonly string[], unverified: readonly string[] = []): Run => ({
+  check,
+  visit,
+  inventory,
+  found,
+  unverified,
+});
+
+const targetsRun = Effect.fn("targetsRun")(function* ({ browser, declaration, visit, url }: Visiting) {
+  const targets = targetsOn(declaration, visit.route.path);
+  const { page } = yield* openVisit(browser, visit);
+  yield* load(page, url);
+  const { found, visible } = yield* judgeTargets(page, targets);
+  const inventory = [...visible].map(([name, count]) => `${name} ${count}`);
+  return run("targets", visit, inventory, targets.length === 0 ? [...found, NO_TARGET] : found);
+}, Effect.scoped);
+
+const layoutRun = Effect.fn("layoutRun")(function* ({ browser, declaration, visit, url }: Visiting) {
+  const { cdp, page } = yield* openVisit(browser, visit);
+  yield* load(page, url);
+  const { found, scanned, parked } = yield* judgeLayout(cdp, targetsOn(declaration, visit.route.path));
+  const inventory = [...counted(scanned.map(({ name }) => name)), ...counted(parked).map((one) => `${one} parked until focused`)];
+  return run("layout", visit, inventory, scanned.length === 0 ? [...found, NO_TARGET] : found);
+}, Effect.scoped);
+
+const keyboardRun = Effect.fn("keyboardRun")(function* ({ browser, declaration, visit, url }: Visiting) {
+  const targets = targetsOn(declaration, visit.route.path).filter(({ focusable }) => focusable === true);
+  const { page } = yield* openVisit(browser, visit);
+  yield* load(page, url);
+  const { found, reached } = yield* judgeKeyboard(page, targets);
+  const inventory = [...reached].map(([name, times]) => `${name} ${times}`);
+  return run("keyboard", visit, inventory, targets.length === 0 || reached.size === 0 ? [...found, NO_TARGET] : found);
+}, Effect.scoped);
+
+const motionRun = Effect.fn("motionRun")(function* ({ browser, visit, url }: Visiting) {
+  const { page } = yield* openVisit(browser, visit, recordMotion);
+  yield* load(page, url);
+  const { found, controls, unhovered } = yield* judgeStillness(page);
+  const inventory = [`${controls} control(s)`, ...(unhovered === 0 ? [] : [`${unhovered} it cannot hover, judged on focus alone`])];
+  return run("motion", visit, inventory, controls === 0 ? [...found, "scanned no control"] : found);
+}, Effect.scoped);
+
+const axeRun = Effect.fn("axeRun")(function* ({ browser, visit, url }: Visiting) {
+  const { page } = yield* openVisit(browser, visit);
+  yield* load(page, url);
+  const { found, unverified, rules } = yield* judgeAxe(page);
+  return run("axe", visit, [`${rules} rule(s)`], rules === 0 ? [...found, "axe ran no rule"] : found, unverified);
+}, Effect.scoped);
+
+const nestingRun = Effect.fn("nestingRun")(function* ({ browser, visit, url }: Visiting) {
+  const { page } = yield* openVisit(browser, visit);
+  yield* load(page, url);
+  const { found, elements } = yield* judgeNesting(page);
+  return run("nesting", visit, [`${elements} element(s)`], found);
+}, Effect.scoped);
+
+const assetsRun = Effect.fn("assetsRun")(function* ({ browser, visit, url }: Visiting) {
+  const { page } = yield* openVisit(browser, visit);
+  const watch = watchAssets(page);
+  yield* attempt(`cannot load ${url}`, () => page.goto(url, { waitUntil: "networkidle" }));
+  return run("assets", visit, [`${watch.requested()} request(s)`], watch.found());
+}, Effect.scoped);
+
+const hookRun = Effect.fn("hookRun")(function* (check: ProductCheck, { browser, visit, url }: Visiting) {
+  const { page } = yield* openVisit(browser, visit);
+  const { targets, found } = yield* runHook(check, page, { ...visit, url });
+  return run(`hook ${check.name}`, visit, counted(targets), targets.length === 0 ? [...found, NO_TARGET] : found);
+}, Effect.scoped);
+
+const BUILT_IN: Readonly<Record<CheckName, (visiting: Visiting) => Effect.Effect<Run, BrowserFailure>>> = {
+  layout: layoutRun,
+  keyboard: keyboardRun,
+  motion: motionRun,
+  axe: axeRun,
+  nesting: nestingRun,
+  assets: assetsRun,
+};
+
+function applies(check: CheckName, { state }: Visit): boolean {
+  return check !== "motion" || state.reducedMotion === "reduce";
+}
+
+const checkSite = Effect.fn("checkSite")(function* (root: string, declaration: Declaration) {
+  const site = yield* readSite(root, declaration.site);
+  const paths = declaration.routes.map(({ path }) => path);
+  const hooks = declaration.hooks === undefined ? [] : yield* loadHooks(root, declaration.hooks, paths);
+  const missingRoutes = paths.filter((path) => !site.files.has(path));
+  const origin = yield* serveSite(site);
+  const browser = yield* launchChrome;
+  const runs: Run[] = [];
+  for (const visit of visitsOf(declaration).filter(({ route }) => !missingRoutes.includes(route.path))) {
+    const visiting = { browser, declaration, visit, url: new URL(visit.route.path, origin).href };
+    runs.push(yield* targetsRun(visiting));
+    for (const check of declaration.checks.filter((one) => applies(one, visit))) runs.push(yield* BUILT_IN[check](visiting));
+    for (const hook of hooks.filter(({ routes }) => routes === undefined || routes.includes(visit.route.path))) runs.push(yield* hookRun(hook, visiting));
+  }
+  return { runs, missingRoutes };
+}, Effect.scoped);
+
+const browserChecks = Effect.gen(function* () {
+  const root = (yield* Path.Path).resolve(process.argv[2] ?? ".");
+  const declaration = yield* readDeclaration(root);
+  const outcome = yield* checkSite(root, declaration);
+  yield* Console.log(report(declaration, outcome));
+  return passes(outcome);
+});
+
+if (import.meta.main) runMain(NAME, browserChecks);