@avi2dg/checks 0.34.0 → 0.35.1

package/src/delivery/ci-wiring.ts

@@ -3,7 +3,8 @@ 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 { fromProgram, invokes, mentions, plainCommand, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+import { readShellFiles, runsMutation, within, type Run } from "./mutation-job.ts";
+import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
 
 export type { Command };
 
@@ -39,6 +40,7 @@ export type Visibility = "private" | "public" | "unknown";
 export type RunnerPolicy = {
   readonly visibility: Visibility;
   readonly scripts: ReadonlyMap<string, string>;
+  readonly files?: ReadonlyMap<string, string>;
 };
 
 export type RunnerFault = {
@@ -76,10 +78,6 @@ 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> {
@@ -266,29 +264,6 @@ 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));
@@ -310,18 +285,37 @@ function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility)
   return `the job is not on a hosted runner CI_RUNS_ON can override; set runs-on: ${HOSTED_DEFAULT}`;
 }
 
+function stepDirectory(value: unknown, inherited: string | undefined): string | undefined {
+  if (value === undefined) return inherited;
+  return typeof value === "string" ? within("", value) : undefined;
+}
+
+function defaultDirectory(node: unknown, inherited: string | undefined): string | undefined {
+  const defaults = isRecord(node) ? node["defaults"] : undefined;
+  const run = isRecord(defaults) ? defaults["run"] : undefined;
+  return stepDirectory(isRecord(run) ? run["working-directory"] : undefined, inherited);
+}
+
+function jobRuns(workflow: Workflow, job: Readonly<Record<string, unknown>>): readonly Run[] {
+  const dir = defaultDirectory(job, defaultDirectory(workflow.document, ""));
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  return steps.flatMap((step: unknown) => (isRecord(step) && typeof step["run"] === "string" ? [{ script: step["run"], dir: stepDirectory(step["working-directory"], dir) }] : []));
+}
+
+function workflowJobs(workflow: Workflow): readonly (readonly [string, Readonly<Record<string, unknown>>])[] {
+  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+  return isRecord(jobs) ? Object.entries(jobs).flatMap(([id, job]) => (isRecord(job) ? [[id, job] as const] : [])) : [];
+}
+
 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));
+  return workflows.flatMap((workflow) =>
+    workflowJobs(workflow).flatMap(([id, job]) => {
+      if (job["runs-on"] === undefined) return [];
+      const mutation = jobRuns(workflow, job).some((run) => runsMutation(run, policy.scripts, (file) => policy.files?.get(file)));
       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 {
@@ -383,7 +377,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);
-  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts: yield* readScripts(root) }, workflows);
+  const scripts = yield* readScripts(root);
+  const runs = workflows.flatMap((workflow) => workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job)));
+  const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts, files: yield* readShellFiles(root, scripts, runs) }, workflows);
   if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
   return gaps.length === 0 && faults.length === 0;
 });

package/src/delivery/mutation-job.ts

@@ -0,0 +1,131 @@
+import { Effect, FileSystem, Path } from "effect";
+import { fromProgram, SHELLS, shellCommands, withoutOptions, type Command } from "./shell-command.ts";
+
+// An undefined directory is one known only at run time.
+export type Run = {
+  readonly script: string;
+  readonly dir: string | undefined;
+};
+
+type Invocation =
+  | { readonly script: string; readonly body: string }
+  | { readonly program: Command; readonly file: string | undefined; readonly dir: string | undefined };
+
+type Walked = {
+  readonly scripts: readonly string[];
+  readonly files: readonly string[];
+};
+
+type Context = {
+  readonly scripts: ReadonlyMap<string, string>;
+  readonly files: (file: string) => string | undefined;
+};
+
+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 SHELL_SHEBANG = new RegExp(String.raw`^#!\s*(?:\S*\/)?(?:env\s+(?:-\S+\s+)*)?(?:${SHELLS.join("|")})(?:\s|$)`);
+const UNRESOLVED = /^[/~]|[$`]/;
+const ROOT = "";
+
+export function within(dir: string | undefined, path: string): string | undefined {
+  if (dir === undefined || UNRESOLVED.test(path)) return undefined;
+  const resolved = dir === ROOT ? [] : dir.split("/");
+  for (const part of path.split("/")) {
+    if (part === ".." && resolved.length === 0) return undefined;
+    if (part === "..") resolved.pop();
+    else if (part !== "" && part !== ".") resolved.push(part);
+  }
+  return resolved.join("/");
+}
+
+export function runsMutation(run: Run, scripts: ReadonlyMap<string, string>, files: (file: string) => string | undefined): boolean {
+  return scriptRunsMutation(run.script, run.dir, { scripts, files }, { scripts: [], files: [] });
+}
+
+function scriptRunsMutation(script: string, dir: string | undefined, context: Context, walked: Walked): boolean {
+  let cwd = dir;
+  for (const command of shellCommands(script)) {
+    const [program = "", ...args] = fromProgram(command);
+    if (program === "cd") cwd = changedDirectory(cwd, withoutOptions(args, new Set()));
+    else if (mutationCommand(command, cwd, context, walked)) return true;
+  }
+  return false;
+}
+
+function changedDirectory(cwd: string | undefined, [target]: Command): string | undefined {
+  return target === undefined || target === "-" ? undefined : within(cwd, target);
+}
+
+function bunOptions(words: Command): Command {
+  return words.slice(0, words.length - withoutOptions(words, BUN_OPERANDS).length);
+}
+
+function bunDirectory(options: Command, dir: string | undefined): string | undefined {
+  return options.reduce<string | undefined>((current, word, index) => {
+    const value = word === "--cwd" ? options[index + 1] : word.startsWith("--cwd=") ? word.slice("--cwd=".length) : undefined;
+    return value === undefined ? current : within(dir, value);
+  }, dir);
+}
+
+function fileAt(dir: string | undefined, path: string): string | undefined {
+  return within(dir, path) || undefined;
+}
+
+function invocation(command: Command, dir: string | undefined, context: Context, walked: Walked): Invocation | undefined {
+  const [first = "", ...rest] = fromProgram(command);
+  if (first !== "bun") return { program: [first, ...rest], file: first.includes("/") ? fileAt(dir, first) : undefined, dir };
+  const [subcommand = "", ...operands] = withoutOptions(rest, BUN_OPERANDS);
+  if (subcommand === "x") return invocation(["bunx", ...operands], dir, context, walked);
+  if (BUN_COMMANDS.has(subcommand)) return undefined;
+  const [target = "", ...targetArgs] = subcommand === "run" ? withoutOptions(operands, BUN_OPERANDS) : [subcommand, ...operands];
+  const cwd = bunDirectory([...bunOptions(rest), ...(subcommand === "run" ? bunOptions(operands) : [])], dir);
+  const body = walked.scripts.includes(target) ? undefined : context.scripts.get(target);
+  return body === undefined ? { program: [target, ...targetArgs], file: fileAt(cwd, target), dir: cwd } : { script: target, body };
+}
+
+function mutationCommand(command: Command, dir: string | undefined, context: Context, walked: Walked): boolean {
+  const call = invocation(command, dir, context, walked);
+  if (call === undefined) return false;
+  // bun runs a script from the directory of the package.json that names it.
+  if ("body" in call) return scriptRunsMutation(call.body, ROOT, context, { ...walked, scripts: [...walked.scripts, call.script] });
+  return mutationBin(call.program) || fileRunsMutation(call.file, call.dir, context, walked);
+}
+
+// A script file runs in its caller's directory, not its own.
+function fileRunsMutation(file: string | undefined, dir: string | undefined, context: Context, walked: Walked): boolean {
+  if (file === undefined || walked.files.includes(file)) return false;
+  const body = context.files(file);
+  return body !== undefined && scriptRunsMutation(body, dir, context, { ...walked, files: [...walked.files, file] });
+}
+
+function mutationBin([program = "", subcommand]: Command): boolean {
+  const bin = program.slice(program.lastIndexOf("/") + 1);
+  return MUTATION_BINS.includes(bin) || (bin === "stryker" && subcommand === "run");
+}
+
+function filesWanted(runs: readonly Run[], scripts: ReadonlyMap<string, string>, files: ReadonlyMap<string, string>, read: ReadonlySet<string>): readonly string[] {
+  const wanted = new Set<string>();
+  const lookup = (file: string) => {
+    if (!read.has(file)) wanted.add(file);
+    return files.get(file);
+  };
+  for (const run of runs) runsMutation(run, scripts, lookup);
+  return [...wanted];
+}
+
+export const readShellFiles = Effect.fn("readShellFiles")(function* (root: string, scripts: ReadonlyMap<string, string>, runs: readonly Run[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const contents = new Map<string, string>();
+  const read = new Set<string>();
+  for (let wanted = filesWanted(runs, scripts, contents, read); wanted.length > 0; wanted = filesWanted(runs, scripts, contents, read)) {
+    for (const file of wanted) {
+      read.add(file);
+      const text = yield* fs.readFileString(path.join(root, file)).pipe(Effect.orElseSucceed(() => undefined));
+      if (text !== undefined && (file.endsWith(".sh") || SHELL_SHEBANG.test(text))) contents.set(file, text);
+    }
+  }
+  return contents;
+});

package/src/delivery/shell-command.ts

@@ -70,6 +70,7 @@ const COMMAND_BREAKS = new Set(["\n", ";", "&", "|", "(", ")", "`"]);
 const WORD_BREAKS = new Set([" ", "\t"]);
 const REDIRECTS = new Set(["<", ">"]);
 const REDIRECT_OPERATOR = /^[<>][<>&|]*/;
+const DELIMITER_BREAKS = new Set([...WORD_BREAKS, ...COMMAND_BREAKS, ...REDIRECTS]);
 const FILE_DESCRIPTOR = /^\d+$/;
 const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
@@ -138,9 +139,19 @@ function commentEnd(script: string, from: number): number {
   return newline === -1 ? script.length : newline;
 }
 
+export const SHELLS = ["sh", "bash", "dash", "ksh", "zsh"];
+
+type Heredoc = {
+  readonly consumer: Command;
+  readonly delimiter: string;
+  readonly tabs: boolean;
+  readonly literal: boolean;
+};
+
 type ShellParse = {
   readonly commands: string[][];
   readonly substitutions: string[];
+  readonly heredocs: Heredoc[];
   words: string[];
   word: string | undefined;
   redirecting: boolean;
@@ -163,12 +174,63 @@ function endCommand(parse: ShellParse): void {
 function startRedirect(parse: ShellParse, script: string, index: number): number {
   if (parse.word !== undefined && FILE_DESCRIPTOR.test(parse.word)) parse.word = undefined;
   endWord(parse);
+  const operator = REDIRECT_OPERATOR.exec(script.slice(index))?.[0] ?? script.charAt(index);
+  if (operator === "<<") return startHeredoc(parse, script, index + operator.length);
   parse.redirecting = true;
-  return index + (REDIRECT_OPERATOR.exec(script.slice(index))?.[0].length ?? 1);
+  return index + operator.length;
+}
+
+function startHeredoc(parse: ShellParse, script: string, from: number): number {
+  const tabs = script.charAt(from) === "-";
+  let start = tabs ? from + 1 : from;
+  while (WORD_BREAKS.has(script.charAt(start))) start += 1;
+  let delimiter = "";
+  let end = start;
+  while (end < script.length && !DELIMITER_BREAKS.has(script.charAt(end))) {
+    const part = shellPart(script, end);
+    delimiter += part.text;
+    end = part.end;
+  }
+  parse.heredocs.push({ consumer: parse.words, delimiter, tabs, literal: /['"\\]/.test(script.slice(start, end)) });
+  return end;
+}
+
+function heredocBody(script: string, from: number, { delimiter, tabs }: Heredoc): Span {
+  let line = from;
+  while (line < script.length) {
+    const lineEnd = commentEnd(script, line);
+    const text = script.slice(line, lineEnd);
+    if ((tabs ? text.replace(/^\t+/, "") : text) === delimiter) return { text: script.slice(from, line), end: lineEnd + 1 };
+    line = lineEnd + 1;
+  }
+  return { text: script.slice(from), end: script.length };
+}
+
+function bodySubstitutions(body: string): readonly string[] {
+  const substitutions: string[] = [];
+  let index = 0;
+  while (index < body.length) {
+    const part = doubleQuotedPart(body, index);
+    substitutions.push(...part.substitutions);
+    index = part.end;
+  }
+  return substitutions;
+}
+
+function skipHeredocs(parse: ShellParse, script: string, from: number): number {
+  let index = from;
+  for (const heredoc of parse.heredocs.splice(0)) {
+    const body = heredocBody(script, index, heredoc);
+    const [program = ""] = fromProgram(heredoc.consumer);
+    if (SHELLS.includes(program.slice(program.lastIndexOf("/") + 1))) parse.substitutions.push(body.text);
+    else if (!heredoc.literal) parse.substitutions.push(...bodySubstitutions(body.text));
+    index = body.end;
+  }
+  return index;
 }
 
 export function shellCommands(script: string): readonly Command[] {
-  const parse: ShellParse = { commands: [], substitutions: [], words: [], word: undefined, redirecting: false };
+  const parse: ShellParse = { commands: [], substitutions: [], heredocs: [], words: [], word: undefined, redirecting: false };
   let index = 0;
   while (index < script.length) {
     const char = script.charAt(index);
@@ -178,9 +240,11 @@ export function shellCommands(script: string): readonly Command[] {
       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);
+    } else if (COMMAND_BREAKS.has(char)) {
+      endCommand(parse);
+      index = char === "\n" ? skipHeredocs(parse, script, index + 1) : index + 1;
+    } else if (WORD_BREAKS.has(char)) {
+      endWord(parse);
       index += 1;
     } else {
       const part = shellPart(script, index);

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);