@avi2dg/checks 0.34.0 → 0.35.1

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 },
 };