@avi2dg/checks 0.34.0 → 0.35.0

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

package/src/quality/browser/declaration.ts

@@ -0,0 +1,107 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { Usage } from "../../core/main.ts";
+
+const DECLARATION = "browser-checks.json";
+
+const CHECKS = ["layout", "keyboard", "motion", "axe", "nesting", "assets"] as const;
+
+export type CheckName = (typeof CHECKS)[number];
+
+const Name = Schema.NonEmptyString;
+const Pixels = Schema.Int.check(Schema.isGreaterThan(0));
+
+const Route = Schema.Struct({
+  path: Schema.String.check(Schema.isPattern(/^\//, { message: "is not a path from the site root, such as /ru/" })),
+  locale: Name,
+});
+
+const Viewport = Schema.Struct({ name: Name, width: Pixels, height: Pixels, touch: Schema.optionalKey(Schema.Boolean) });
+
+const State = Schema.Struct({
+  name: Name,
+  textPx: Schema.optionalKey(Pixels),
+  reducedMotion: Schema.optionalKey(Schema.Literals(["reduce", "no-preference"])),
+});
+
+const Target = Schema.Struct({
+  name: Name,
+  selector: Name,
+  routes: Schema.optionalKey(Schema.NonEmptyArray(Name)),
+  focusable: Schema.optionalKey(Schema.Boolean),
+});
+
+const Declaration = Schema.Struct({
+  site: Name,
+  routes: Schema.NonEmptyArray(Route),
+  viewports: Schema.NonEmptyArray(Viewport),
+  states: Schema.NonEmptyArray(State),
+  targets: Schema.NonEmptyArray(Target),
+  checks: Schema.NonEmptyArray(Schema.Literals(CHECKS)),
+  hooks: Schema.optionalKey(Name),
+});
+
+export type Route = typeof Route.Type;
+export type Viewport = typeof Viewport.Type;
+export type State = typeof State.Type;
+export type Target = typeof Target.Type;
+export type Declaration = typeof Declaration.Type;
+
+export type Visit = {
+  readonly route: Route;
+  readonly viewport: Viewport;
+  readonly state: State;
+};
+
+const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+
+function repeated(names: readonly string[]): readonly string[] {
+  return [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
+}
+
+export function inconsistencies(declaration: Declaration): readonly string[] {
+  const paths = declaration.routes.map(({ path }) => path);
+  const found = [
+    ...repeated(paths).map((path) => `route ${path} is declared twice`),
+    ...repeated(declaration.viewports.map(({ name }) => name)).map((name) => `viewport ${name} is declared twice`),
+    ...repeated(declaration.states.map(({ name }) => name)).map((name) => `state ${name} is declared twice`),
+    ...repeated(declaration.targets.map(({ name }) => name)).map((name) => `target ${name} is declared twice`),
+    ...repeated(declaration.checks).map((check) => `check ${check} is declared twice`),
+    ...declaration.targets.flatMap(({ name, routes = [] }) =>
+      routes.filter((path) => !paths.includes(path)).map((path) => `target ${name} names route ${path}, which no route declares`),
+    ),
+  ];
+  if (declaration.checks.includes("motion") && !declaration.states.some(({ reducedMotion }) => reducedMotion === "reduce")) {
+    found.push("check motion judges a visitor who turns motion off, and no state sets reducedMotion to reduce");
+  }
+  if (declaration.checks.includes("keyboard") && !declaration.targets.some(({ focusable }) => focusable === true)) {
+    found.push("check keyboard judges the targets Tab reaches, and no target sets focusable");
+  }
+  return found;
+}
+
+export 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 product opts in to the browser checks by declaring its pages there` });
+  }
+  const declaration = yield* decodeDeclaration(yield* fs.readFileString(file)).pipe(
+    Effect.mapError(({ message }) => new Usage({ message: `${DECLARATION} does not decode: ${message}` })),
+  );
+  const found = inconsistencies(declaration);
+  if (found.length > 0) return yield* new Usage({ message: `${DECLARATION}: ${found.join("; ")}` });
+  return declaration;
+});
+
+export function visitsOf({ routes, viewports, states }: Declaration): readonly Visit[] {
+  return routes.flatMap((route) => viewports.flatMap((viewport) => states.map((state) => ({ route, viewport, state }))));
+}
+
+export function targetsOn(declaration: Declaration, path: string): readonly Target[] {
+  return declaration.targets.filter(({ routes }) => routes === undefined || routes.includes(path));
+}
+
+export function describeVisit({ route, viewport, state }: Visit): string {
+  const touch = viewport.touch === true ? " touch" : "";
+  return `${route.path} (${route.locale}), ${viewport.name} ${viewport.width}x${viewport.height}${touch}, ${state.name}`;
+}

package/src/quality/browser/dom.ts

@@ -0,0 +1,121 @@
+import { Effect } from "effect";
+import type { CDPSession } from "playwright-core";
+import { attempt, BrowserFailure } from "./page.ts";
+
+export type Rect = {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+};
+
+type TreeNode = {
+  readonly nodeId: number;
+  readonly backendNodeId: number;
+  readonly children?: readonly TreeNode[];
+  readonly pseudoElements?: readonly TreeNode[];
+  readonly shadowRoots?: readonly TreeNode[];
+  readonly contentDocument?: TreeNode;
+};
+
+export type Dom = {
+  readonly cdp: CDPSession;
+  readonly rootId: number;
+  readonly backendOf: ReadonlyMap<number, number>;
+  readonly parentOf: ReadonlyMap<number, number>;
+};
+
+export const readDom = Effect.fn("readDom")(function* (cdp: CDPSession) {
+  const { root } = yield* attempt("cannot read the DOM", () => cdp.send("DOM.getDocument", { depth: -1, pierce: true }));
+  const backendOf = new Map<number, number>();
+  const parentOf = new Map<number, number>();
+  const visit = (node: TreeNode): void => {
+    backendOf.set(node.nodeId, node.backendNodeId);
+    const { children = [], pseudoElements = [], shadowRoots = [], contentDocument } = node;
+    for (const child of [...children, ...pseudoElements, ...shadowRoots, ...(contentDocument === undefined ? [] : [contentDocument])]) {
+      parentOf.set(child.backendNodeId, node.backendNodeId);
+      visit(child);
+    }
+  };
+  visit(root);
+  return { cdp, rootId: root.nodeId, backendOf, parentOf } satisfies Dom;
+});
+
+export const querySelectorAll = Effect.fn("querySelectorAll")(function* (dom: Dom, selector: string) {
+  const { nodeIds } = yield* attempt(`cannot query ${selector}`, () => dom.cdp.send("DOM.querySelectorAll", { nodeId: dom.rootId, selector }));
+  return nodeIds.flatMap((nodeId) => {
+    const backend = dom.backendOf.get(nodeId);
+    return backend === undefined ? [] : [backend];
+  });
+});
+
+export function isWithin(dom: Dom, node: number, ancestor: number): boolean {
+  for (let at: number | undefined = node; at !== undefined; at = dom.parentOf.get(at)) {
+    if (at === ancestor) return true;
+  }
+  return false;
+}
+
+function rectOfQuad(quad: readonly number[]): Rect {
+  const xs = quad.filter((_, index) => index % 2 === 0);
+  const ys = quad.filter((_, index) => index % 2 === 1);
+  return { left: Math.min(...xs), top: Math.min(...ys), right: Math.max(...xs), bottom: Math.max(...ys) };
+}
+
+// Chromium refuses an element with no layout box rather than answering with no quads.
+const NO_LAYOUT_BOX = "Could not compute content quads";
+
+export const lineRects = Effect.fn("lineRects")(function* (dom: Dom, backendNodeId: number) {
+  const { quads } = yield* attempt("cannot read an element's boxes", () => dom.cdp.send("DOM.getContentQuads", { backendNodeId })).pipe(
+    Effect.catchTag("BrowserFailure", (failure) => (failure.message.includes(NO_LAYOUT_BOX) ? Effect.succeed({ quads: [] }) : Effect.fail(failure))),
+  );
+  return quads.map(rectOfQuad).filter((rect) => rect.right - rect.left > 0 && rect.bottom - rect.top > 0);
+});
+
+export function overlapArea(a: Rect, b: Rect): number {
+  const width = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+  const height = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+  return width > 0 && height > 0 ? width * height : 0;
+}
+
+export type Viewport = {
+  readonly width: number;
+  readonly height: number;
+  readonly contentWidth: number;
+  readonly scrollX: number;
+  readonly scrollY: number;
+};
+
+export const viewportOf = Effect.fn("viewportOf")(function* (cdp: CDPSession) {
+  const { cssLayoutViewport, cssContentSize } = yield* attempt("cannot read the layout metrics", () => cdp.send("Page.getLayoutMetrics"));
+  return {
+    width: cssLayoutViewport.clientWidth,
+    height: cssLayoutViewport.clientHeight,
+    contentWidth: cssContentSize.width,
+    scrollX: cssLayoutViewport.pageX,
+    scrollY: cssLayoutViewport.pageY,
+  } satisfies Viewport;
+});
+
+// Content quads are relative to the viewport, and the hit test takes coordinates relative to the document.
+export const nodeAt = Effect.fn("nodeAt")(function* (dom: Dom, viewport: Viewport, x: number, y: number) {
+  const { backendNodeId } = yield* attempt("cannot hit-test the page", () =>
+    dom.cdp.send("DOM.getNodeForLocation", { x: Math.round(x + viewport.scrollX), y: Math.round(y + viewport.scrollY) }),
+  );
+  return backendNodeId;
+});
+
+export const callOn = Effect.fn("callOn")(function* (dom: Dom, backendNodeId: number, functionDeclaration: string) {
+  const { object } = yield* attempt("cannot resolve an element", () => dom.cdp.send("DOM.resolveNode", { backendNodeId }));
+  const { objectId } = object;
+  if (objectId === undefined) return yield* new BrowserFailure({ message: `node ${backendNodeId} resolved to no object` });
+  const { result } = yield* attempt("cannot call into the page", () =>
+    dom.cdp.send("Runtime.callFunctionOn", { objectId, functionDeclaration, returnByValue: true }),
+  );
+  const value: unknown = result.value;
+  return value;
+});
+
+export const evaluate = Effect.fn("evaluate")(function* (cdp: CDPSession, expression: string) {
+  yield* attempt("cannot evaluate in the page", () => cdp.send("Runtime.evaluate", { expression }));
+});

package/src/quality/browser/hooks.ts

@@ -0,0 +1,57 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import type { Page } from "playwright-core";
+import { Usage } from "../../core/main.ts";
+import type { Route, State, Viewport } from "./declaration.ts";
+import { attempt } from "./page.ts";
+
+export type HookVisit = {
+  readonly route: Route;
+  readonly viewport: Viewport;
+  readonly state: State;
+  readonly url: string;
+};
+
+const HookResult = Schema.Struct({ targets: Schema.Array(Schema.String), found: Schema.Array(Schema.String) });
+
+export type HookResult = typeof HookResult.Type;
+
+type RunHook = (page: Page, visit: HookVisit) => Promise<HookResult>;
+
+const isRunHook = (value: unknown): value is RunHook => typeof value === "function";
+
+const ProductCheck = Schema.Struct({
+  name: Schema.NonEmptyString,
+  routes: Schema.optionalKey(Schema.NonEmptyArray(Schema.NonEmptyString)),
+  run: Schema.declare(isRunHook, { expected: "a function from a page and a visit to a promised result" }),
+});
+
+export type ProductCheck = typeof ProductCheck.Type;
+
+const decodeHookModule = Schema.decodeUnknownEffect(Schema.Struct({ checks: Schema.NonEmptyArray(ProductCheck) }));
+
+const decodeHookResult = Schema.decodeUnknownEffect(HookResult);
+
+export const loadHooks = Effect.fn("loadHooks")(function* (root: string, hooks: string, paths: readonly string[]) {
+  const file = (yield* Path.Path).resolve(root, hooks);
+  if (!(yield* (yield* FileSystem.FileSystem).exists(file))) return yield* new Usage({ message: `the declared hooks module ${hooks} is missing` });
+  const loaded: unknown = yield* attempt(`cannot load the hooks module ${hooks}`, () => import(file)).pipe(
+    Effect.mapError(({ message }) => new Usage({ message })),
+  );
+  const { checks } = yield* decodeHookModule(loaded).pipe(
+    Effect.mapError(({ message }) => new Usage({ message: `the hooks module ${hooks} exports no checks a runner can call: ${message}` })),
+  );
+  const names = checks.map(({ name }) => name);
+  const problems = [
+    ...names.filter((name, index) => names.indexOf(name) !== index).map((name) => `hook ${name} is exported twice`),
+    ...checks.flatMap(({ name, routes = [] }) => routes.filter((path) => !paths.includes(path)).map((path) => `hook ${name} names route ${path}, which no route declares`)),
+  ];
+  if (problems.length > 0) return yield* new Usage({ message: `${hooks}: ${problems.join("; ")}` });
+  return checks;
+});
+
+export const runHook = Effect.fn("runHook")(function* (check: ProductCheck, page: Page, visit: HookVisit) {
+  return yield* attempt(`hook ${check.name} throws`, () => check.run(page, visit)).pipe(
+    Effect.flatMap((result) => decodeHookResult(result).pipe(Effect.mapError(({ message }) => ({ message: `hook ${check.name} returns no result: ${message}` })))),
+    Effect.catch(({ message }) => Effect.succeed({ targets: [], found: [message] })),
+  );
+});

package/src/quality/browser/keyboard.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect";
+import type { Page } from "playwright-core";
+import type { Target } from "./declaration.ts";
+import { attempt } from "./page.ts";
+import { countVisible } from "./targets.ts";
+
+const FOCUS_RING_MARGIN_PX = 6;
+
+// A focus trap would hold Tab on the page forever, so the walk gives up past this many stops.
+const STOP_LIMIT = 500;
+
+type KeyboardReport = {
+  readonly found: readonly string[];
+  readonly reached: ReadonlyMap<string, number>;
+};
+
+const count = (page: Page, selector: string) => attempt(`cannot query ${selector}`, () => page.locator(selector).count());
+
+const focusedTargets = Effect.fn("focusedTargets")(function* (page: Page, targets: readonly Target[]) {
+  const focused: Target[] = [];
+  for (const target of targets) {
+    const matches = yield* attempt(`cannot query ${target.selector}`, () => page.locator(target.selector).and(page.locator(":focus")).count());
+    if (matches > 0) focused.push(target);
+  }
+  return focused;
+});
+
+const focusRingShows = Effect.fn("focusRingShows")(function* (page: Page) {
+  const focused = yield* attempt("cannot hold the focused element", () => page.locator(":focus").elementHandle());
+  const box = yield* attempt("cannot measure the focused element", () => focused.boundingBox());
+  if (box === null) return false;
+  const clip = {
+    x: Math.max(0, box.x - FOCUS_RING_MARGIN_PX),
+    y: Math.max(0, box.y - FOCUS_RING_MARGIN_PX),
+    width: box.width + 2 * FOCUS_RING_MARGIN_PX,
+    height: box.height + 2 * FOCUS_RING_MARGIN_PX,
+  };
+  const withFocus = yield* attempt("cannot capture the focused element", () => page.screenshot({ clip }));
+  yield* attempt("cannot blur the focused element", () => page.evaluate("document.activeElement.blur()"));
+  const withoutFocus = yield* attempt("cannot capture the blurred element", () => page.screenshot({ clip }));
+  yield* attempt("cannot focus the element again", () => focused.focus());
+  return !withFocus.equals(withoutFocus);
+});
+
+// Past the last stop Tab leaves the page for the browser, and the next press starts over at the first stop.
+const tabToNextStop = Effect.fn("tabToNextStop")(function* (page: Page) {
+  yield* attempt("cannot press Tab", () => page.keyboard.press("Tab"));
+  return (yield* count(page, ":focus")) > 0;
+});
+
+export const judgeKeyboard = Effect.fn("judgeKeyboard")(function* (page: Page, targets: readonly Target[]) {
+  const found: string[] = [];
+  const reached = new Map<string, number>();
+  let stops = 0;
+  while (yield* tabToNextStop(page)) {
+    stops += 1;
+    if (stops > STOP_LIMIT) {
+      found.push(`Tab never leaves the page within ${STOP_LIMIT} stops`);
+      break;
+    }
+    const focused = yield* focusedTargets(page, targets);
+    for (const target of focused) reached.set(target.name, (reached.get(target.name) ?? 0) + 1);
+    if (focused.length > 0 && !(yield* focusRingShows(page))) {
+      found.push(`${focused.map(({ name }) => name).join(" and ")} shows no visible focus when Tab reaches it`);
+    }
+  }
+  for (const target of targets) {
+    const present = yield* countVisible(page, target.selector);
+    if ((reached.get(target.name) ?? 0) !== present) found.push(`Tab reached ${target.name} ${reached.get(target.name) ?? 0} of ${present} time(s)`);
+  }
+  return { found, reached } satisfies KeyboardReport;
+});