@avi2dg/checks 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.35.0
+
+Released 2026-10-07.
+
+### Features
+
+- **quality:** add the opt-in checks-browser runner and checks-frontend-syntax gate [#127](https://github.com/avi2d/checks/pull/127)
+
+### Fixes
+
+- **testing:** cap mutation concurrency at half the available cores [#129](https://github.com/avi2d/checks/pull/129)
+- **docs:** check Russian prose in the sentence length and one-sentence-per-line rules [#126](https://github.com/avi2d/checks/pull/126)
+
 ## 0.34.0
 
 Released 2026-10-03.

package/README.md

@@ -19,6 +19,12 @@ Each repository owns its workflows and native tool configs, as [Native settings]
   - `oxlint` 1.83.0
   - `oxlint-tsgolint` 7.0.2002
   - `typescript` 7.0.2
+- The optional peers, which only an opt-in check loads, at the exact versions the kit pins:
+  - `@axe-core/playwright` 4.13.0
+  - `html-validate` 11.16.0
+  - `playwright-core` 1.63.0
+  - `postcss-html` 2.0.0
+  - `stylelint` 17.16.0
 
 <!-- end generated prerequisites -->
 
@@ -123,6 +129,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | complexity | [`checks-exports`](docs/gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
+| quality | [`checks-frontend-syntax`](docs/gates/checks-frontend-syntax.md) | the working tree | a repository tracking `frontend-syntax.json` |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
 | docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
@@ -146,6 +153,7 @@ These bins run on their own:
 - [`checks-release-pr`](docs/gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
 - [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
+- [`checks-browser`](docs/gates/checks-browser.md) opens a product's built pages in Chrome and fails on the layout, keyboard, motion, accessibility, nesting and asset checks its `browser-checks.json` declares.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.
 The oxlint base, the dependency-cruiser base and the commitlint config run through their own tools, as the pages under Related topics say.
@@ -155,6 +163,7 @@ The oxlint base, the dependency-cruiser base and the commitlint config run throu
 To move a repository to a newer release of the kit:
 
 1. Run the install line again, which moves the kit to its newest release and the peers to the versions it pins.
+   A repository that opted in to `checks-browser` or `checks-frontend-syntax` also reruns the `bun add` line on its page.
 1. Review the Effect overrides in `.oxlintrc.json` and `tsconfig.json` when a release changes their presets.
 1. Copy `node_modules/@avi2dg/checks/bunfig.toml` over `bunfig.toml` again, since `checks-test-layout` compares the copy with the installed preset.
 1. Run `bun run lint`, `bun run typecheck` and `bun run test`.

package/dependency-cruiser.config.js

@@ -47,7 +47,8 @@ export default {
       comment:
         "The import resolves to an installed package the nearest package.json does not declare, so it holds only while something else keeps it hoisted. Declare it in dependencies, devDependencies or peerDependencies.",
       from: {},
-      to: { dependencyTypes: ["npm-no-pkg", "npm-unknown"] },
+      // dependency-cruiser reads every package.json key holding "ependencies" as a list, so peerDependenciesMeta tags a declared peer npm-no-pkg too.
+      to: { dependencyTypes: ["npm-no-pkg", "npm-unknown"], dependencyTypesNot: ["npm", "npm-dev", "npm-optional", "npm-peer"] },
     },
     {
       name: "not-to-unresolvable",

package/docs/configs/dependency-rules.md

@@ -13,7 +13,7 @@ The shared dependency-cruiser base holds a repository's imports to a set of rule
 - `no-circular`
 - `no-orphans`
 - `not-to-dev-dep`, which refuses shipped source importing a dev-only package, and a package listed in `peerDependencies` too is not dev-only
-- `no-non-package-json`, which refuses an import of an installed package that the nearest `package.json` does not declare
+- `no-non-package-json`, which refuses an import of an installed package that the nearest `package.json` does not declare, and counts a peer that `peerDependenciesMeta` marks optional as declared
 - `not-to-unresolvable`, which refuses a specifier nothing installed answers
 - `no-deep-imports`, which refuses a subpath the package's exports map does not publish
 

package/docs/design.md

@@ -73,8 +73,9 @@ Nothing would then say which gate a helper serves.
 A mutation runner's default scope covers `src/`, so the kit's own Stryker run mutates its source with no `mutate` list.
 The testing directory is named `testing` rather than `tests`, because a `src/tests/` beside the root `tests/` would read as a second suite.
 
-Four `exports` keys name a path the file does not sit at, because consumers resolve them by that name.
+Five `exports` keys name a path the file does not sit at, because consumers resolve them by that name.
 `@avi2dg/checks/scripts/test-skips.ts`, `@avi2dg/checks/scripts/comment-matchers.ts` and `@avi2dg/checks/scripts/prose-matchers.ts` point at their files under `src/`.
+`@avi2dg/checks/browser-hooks.ts` points at `src/quality/browser/hooks.ts`, whose types a product's browser hooks import.
 `@avi2dg/checks/templates/*` points at `dist/templates/`.
 A path read without the resolver, such as `node_modules/@avi2dg/checks/scripts/test-skips.ts`, does not exist.
 
@@ -276,6 +277,27 @@ No finding can be accepted.
 A secret has no false positive worth keeping in git, because a placeholder carries the same shape without the value.
 So the gate ignores a repository's `.gitleaks.toml`, `.gitleaksignore` and `gitleaks:allow` comments, which would each let one repository pass what another fails.
 
+## The frontend checks are opt-in
+
+A browser check needs a built site and a browser, and a backend repository has neither.
+So a product opts in by declaring `browser-checks.json`, `checks-lint` never starts a browser, and the browser libraries are optional peers a backend never installs.
+`checks-frontend-syntax` needs no browser and runs inside `checks-lint`, but only where `frontend-syntax.json` declares its inputs, since a repository with no interface has no CSS to hold to it.
+
+Each check wraps a detector that already works rather than a rule of the kit's own.
+The syntax gate runs two of stylelint's built-in rules, `axe` runs axe-core and `nesting` runs one html-validate rule.
+The `layout`, `keyboard` and `motion` probes are the website's own browser tests, generalized after they held on its English and Russian pages.
+A zoom-disabling viewport is judged by axe on the rendered page, because stylelint reads only CSS and html-validate has no rule for the viewport's content.
+
+A check that scans nothing would pass without judging anything, as some detectors do on an empty directory.
+So every run names what it scanned, and an empty input, an unserved route or a target that matches no visible element fails.
+A contrast axe cannot measure is listed as unverified, never counted as a pass.
+
+Valid choices and the order of async results depend on a product's own schema and requests, which no generic check knows.
+So the runner calls the product's hooks at each visit and holds them to the same inventory, rather than guessing at a product's domain.
+
+The runner drives the Chrome a machine already has through `playwright-core`, since Playwright's own browser builds are a separate download of their own.
+GitHub's hosted Ubuntu runners carry Chrome, and `CHROME_PATH` names any other build.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-browser.md

@@ -0,0 +1,201 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-browser
+
+`checks-browser` is the opt-in runner that opens a product's built pages in Chrome and fails on the measurable quality floor its declaration asks for.
+
+## What it checks
+
+It visits each declared route at each declared viewport in each declared state, and runs each declared check on its own fresh page.
+A visit is one route, one viewport and one state.
+Each check judges only the elements of a target that are visible at the visit.
+So a control the page renders once for each breakpoint is judged where it shows.
+
+| Check | What fails | Built on |
+| --- | --- | --- |
+| `layout` | a page wider than the viewport, and a target that overflows the viewport, is reachable only by scrolling sideways, is cut off by a container that cannot scroll, clips its own text or hides its text, overlaps another target, or is covered by any element | the DevTools protocol's boxes and hit test |
+| `keyboard` | a `focusable` target that Tab does not reach once for each visible element it matches, and a Tab stop on a target that shows no visible focus | Playwright's keyboard, and a screenshot of the target with and without focus |
+| `motion` | an animation or a transition longer than one frame that starts during load, on hover, on leaving a hovered control or on focus, and smooth scrolling, for a visitor who turns motion off | the page's own `document.getAnimations()`, in each state whose `reducedMotion` is `reduce` |
+| `axe` | each violation of axe's WCAG 2.2 AA rules, which include `color-contrast`, `nested-interactive`, `meta-viewport` and `target-size` | axe-core through `@axe-core/playwright` |
+| `nesting` | an element the HTML content model does not permit where it sits in the rendered page, such as a `<button>` inside an `<a>` | html-validate's `element-permitted-content` rule |
+| `assets` | a request that fails, and a response with a status of 400 or more, while the page loads to network idle | Playwright's request and response events |
+
+The `motion` check judges what moves on the rendered page, so a `prefers-reduced-motion` query in the source counts for nothing unless the motion stops.
+It runs only in a state whose `reducedMotion` is `reduce`.
+An animation that ends within one frame never moves, so the common reset that shortens every duration to near zero for reduced motion passes.
+Beyond that, durations, easing and how motion feels are judgement, so no check reads them.
+A control the pointer cannot reach, such as a skip link parked off the screen, is judged on focus alone, and the inventory counts it.
+
+`layout` treats text in an SVG `<title>` or `<desc>`, in a `<textarea>`, or that the browser does not render as left out, not hidden.
+Text that is not rendered includes `display: none`, `hidden`, the options of a closed `<select>` and a closed `<details>`.
+An element with `display: contents`, such as a framework island, has no box of its own but its content renders, so its text is judged.
+Transparent, zero-size, `visibility: hidden` and zero-opacity text still fail.
+A `focusable` target parked off the screen or clipped until it is focused, such as a skip link, is left to `keyboard`.
+The `layout` inventory counts it as parked until focused.
+
+It does not yet check the rendered page against a product's declared design tokens, which needs a separate decision.
+
+`axe` reports a contrast it cannot measure as unverified rather than as a pass or a failure.
+Text over a background image or a gradient is such a case, and the report lists each one under its own heading.
+`nested-interactive` catches a control inside an element whose role makes its children presentational, such as a link inside a `<button>` or inside a `role="button"`.
+`nesting` catches a control inside a link, which axe passes.
+Neither sees a parent click handler that fires with a child control's click, which a product hook tests.
+
+### The inventory
+
+The runner prints one line for each check at each visit.
+The line names the route, its locale, the viewport, the state and what the check scanned.
+At every visit, whichever checks are declared, a `targets` run counts the visible elements each target that applies to the route matches.
+For `targets`, `layout`, `keyboard` and a hook, what it scanned is each target by name with the count of its elements.
+
+It fails, rather than passes, when a declaration leaves nothing to judge:
+
+- a declared route the site does not serve
+- a declared target that matches no visible element on a route it applies to
+- a route that no target applies to
+- a `layout` run or a hook that scans no target
+- a `keyboard` run in which Tab reaches no target
+- a `motion` run that finds no visible control
+- an empty list of routes, viewports, states, targets or checks, which the declaration refuses
+
+Each failure names the check, the route, the locale, the viewport and the state, and the target or the element it found.
+
+### Product hooks
+
+Two checks need what only the product knows, its domain schema and its requests.
+The runner calls the product's own hooks for them rather than judging them itself:
+
+- Valid choices: a hook submits each choice a control offers on the real page, and decodes what reaches the boundary with the product's one schema.
+- Async ordering: a hook answers a second request before the first, then reads the visible and the persisted result.
+  It reads them again after a refused request and after a reconnect.
+
+A hook is also where a product clicks a child control and checks that the row around it did not activate too.
+The same hook can hover a control and check that no application state changed.
+
+The declaration names the module in `hooks`.
+The module exports `checks`, each a name, an optional list of the routes it runs on, and a `run` function.
+The runner hands `run` a fresh page at each visit before it loads anything, so the hook can intercept requests, and the visit with its `url`.
+`run` returns the names of the targets it scanned and what it found, and a hook that throws fails with its message:
+
+```ts
+import { Schema } from "effect";
+import type { ProductCheck } from "@avi2dg/checks/browser-hooks.ts";
+import { Language } from "../../src/domain.ts";
+
+export const checks: readonly ProductCheck[] = [
+  {
+    name: "every offered language decodes at the boundary",
+    routes: ["/settings/"],
+    run: async (page, visit) => {
+      const submitted: string[] = [];
+      await page.route("**/api/language", async (route) => {
+        submitted.push(route.request().postData() ?? "");
+        await route.fulfill({ status: 204 });
+      });
+      await page.goto(visit.url);
+      const offered = await page.locator("#language option").evaluateAll((options) => options.map((option) => (option as HTMLOptionElement).value));
+      for (const value of offered) {
+        await page.selectOption("#language", value);
+        await Promise.all([page.waitForRequest("**/api/language"), page.click("#language-form button")]);
+      }
+      return {
+        targets: offered.map(() => "language choice"),
+        found: submitted.filter((value) => !Schema.is(Language)(value)).map((value) => `the language control offers ${value}, which the boundary refuses`),
+      };
+    },
+  },
+];
+```
+
+## What it reads
+
+It reads `browser-checks.json` in the directory it runs in:
+
+```json
+{
+  "site": "dist",
+  "routes": [
+    { "path": "/", "locale": "en" },
+    { "path": "/ru/", "locale": "ru" }
+  ],
+  "viewports": [
+    { "name": "phone", "width": 375, "height": 812, "touch": true },
+    { "name": "desktop", "width": 1280, "height": 800 }
+  ],
+  "states": [
+    { "name": "default" },
+    { "name": "enlarged text", "textPx": 32 },
+    { "name": "reduced motion", "reducedMotion": "reduce" }
+  ],
+  "targets": [
+    { "name": "language switch", "selector": "header a[hreflang]", "focusable": true },
+    { "name": "email contact", "selector": "main a[href^='mailto:']", "routes": ["/", "/ru/"], "focusable": true },
+    { "name": "headline", "selector": "main h1" }
+  ],
+  "checks": ["layout", "keyboard", "motion", "axe", "nesting", "assets"],
+  "hooks": "tests/browser/hooks.ts"
+}
+```
+
+| Field | What it holds |
+| --- | --- |
+| `site` | the directory of the built site, which the runner serves on a local port, an `index.html` answering for its directory |
+| `routes` | each page to visit, as a `path` from the site root and the `locale` it renders |
+| `viewports` | each window to visit in, with a `name`, a `width` and a `height` in pixels, and `touch` for a phone that has touch and a mobile viewport |
+| `states` | each condition to visit in, with a `name`, `textPx` for the browser's default text size, and `reducedMotion` as `reduce` or `no-preference` |
+| `targets` | each named control or text the checks judge, with a CSS `selector`, the `routes` it is on when not every route, and `focusable` when Tab must reach it |
+| `checks` | the built-in checks to run, from `layout`, `keyboard`, `motion`, `axe`, `nesting` and `assets` |
+| `hooks` | the module of product hooks, as a path from the directory the runner runs in |
+
+`textPx` sets the default font size, so text the page sizes in `rem` or `em` grows, as a visitor's own setting makes it grow.
+A declaration that names a route, viewport, state, target or check twice is refused.
+So are a `motion` check with no state whose `reducedMotion` is `reduce`, a `keyboard` check with no `focusable` target, and a target or a hook that names an undeclared route.
+
+It drives the Chrome the machine has, which `CHROME_PATH` names, or Chrome's standard install when it is unset.
+The product installs the optional peers the runner loads, at the versions the kit pins:
+
+```sh
+bun add -d playwright-core@1.63.0 @axe-core/playwright@4.13.0 html-validate@11.16.0
+```
+
+## Arguments
+
+```sh
+checks-browser [<directory>]
+```
+
+It reads the declaration in the directory it runs in, or in the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every check passes at every visit, and every declared route and target is there |
+| 1 | a check fails at a visit, a declared route is not served, a declared target matches no visible element, or a run scans no target |
+| 2 | `browser-checks.json` is missing, does not decode or contradicts itself, the site directory or the hooks module is missing, a peer cannot load, or Chrome cannot start |
+
+## Sample output
+
+```
+browser: targets at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1, headline 1
+browser: layout at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1, headline 1
+browser: keyboard at /ru/ (ru), phone 375x812 touch, enlarged text scanned language switch 1, email contact 1
+browser: axe at /ru/ (ru), phone 375x812 touch, enlarged text scanned 11 rule(s)
+browser: 1 contrast check(s) axe cannot measure, reported as unverified:
+  axe at /ru/ (ru), phone 375x812 touch, enlarged text: color-contrast unverified: header > p: Element's background color could not be determined due to a background image
+browser: 2 failure(s) in 4 check run(s) over 1 route(s), 1 viewport(s), 1 state(s) and 3 target(s):
+  layout at /ru/ (ru), phone 375x812 touch, enlarged text: email contact "Написать письмо владельцу" clips its own text
+  axe at /ru/ (ru), phone 375x812 touch, enlarged text: nested-interactive (serious): button: Interactive controls must not be nested
+```
+
+## When it runs
+
+A product runs it after it builds its site, in a script of its own such as `"test:browser": "astro build && checks-browser"`.
+`checks-lint` never runs it, and a repository without `browser-checks.json` never starts a browser or needs the peers.
+
+## Related topics
+
+- [checks-frontend-syntax](checks-frontend-syntax.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-frontend-syntax.md

@@ -0,0 +1,97 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-frontend-syntax
+
+`checks-frontend-syntax` is the opt-in gate that refuses two CSS constraints a program can decide: a transition over `all` and a body-wide `user-select`.
+
+## What it checks
+
+It runs stylelint with two of stylelint's own rules, and with no other rule and no repository config:
+
+| Rule | What it refuses | Why |
+| --- | --- | --- |
+| `declaration-property-value-disallowed-list` | `all` in the value of `transition` or `transition-property`, vendor prefixes included, such as `transition: all 200ms` or `-webkit-transition: opacity 1s, all 1s` | every property that changes then animates, including the ones that make the browser lay out the page again |
+| `rule-selector-property-disallowed-list` | `user-select` or a prefixed `user-select` such as `-webkit-user-select` in a rule whose selector list holds `html`, `body`, `:root` or `*`, or one of them inside `:global()` | a visitor cannot select or copy any text on the page |
+
+The second rule refuses any value on those selectors, so `body { user-select: text; }` fails as well.
+It matches each item of the selector list as a whole.
+So it does not follow `:is()`, `:where()` or `:not()`, nor a compound such as `html body` or `body *`.
+A nested rule is judged by its own selector, so `.card { * { user-select: none; } }` fails as `*`.
+A control that needs selection off sets it on its own selector, such as `.drag-handle { user-select: none; }`, which passes.
+
+It judges each `.css` file, and each `<style>` block and `style` attribute in an `.html`, `.astro`, `.vue` or `.svelte` file, through `postcss-html`.
+It reports a file that does not parse, since it cannot judge one.
+It fails on each declared input that matches no file, so an input that a renamed directory or a skipped build leaves empty never passes.
+
+These are outside what it decides:
+
+- A `transition` shorthand that names no property, such as `transition: 200ms`, which the browser reads as `all`.
+- A value it cannot see, such as `transition: var(--motion)` or a style a script sets.
+- `user-select: none` in a `style` attribute on `<body>`, which has no selector to judge.
+- A viewport that disables zoom, since stylelint reads only CSS.
+  A repository that runs only this gate gets no viewport check, and [checks-browser](checks-browser.md) refuses one on the rendered page through axe's `meta-viewport` rule.
+- Whether motion respects a visitor who turns it off, which only the rendered page shows, as the `motion` check of [checks-browser](checks-browser.md) says.
+  A `prefers-reduced-motion` query in the source proves nothing about what moves.
+
+## What it reads
+
+It reads `frontend-syntax.json` in the directory it runs in, which lists the inputs as globs:
+
+```json
+{
+  "inputs": ["src/**/*.css", "src/**/*.astro", "dist/**/*.html"]
+}
+```
+
+A glob over built output, such as `dist/**/*.html`, judges the styles a framework or a CSS tool generates, and needs the build to run first.
+stylelint resolves each glob from that directory, skips `node_modules/` and honours `.stylelintignore`.
+It reads the working tree, so an uncommitted file is judged like a committed one.
+
+The repository installs the two optional peers the gate loads, at the versions the kit pins:
+
+```sh
+bun add -d stylelint@17.16.0 postcss-html@2.0.0
+```
+
+## Arguments
+
+```sh
+checks-frontend-syntax [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every declared input matches a file, and no file holds a refused declaration |
+| 1 | a file holds a refused declaration or does not parse, or a declared input matches no file |
+| 2 | `frontend-syntax.json` is missing or does not decode, its input list is empty, or stylelint or `postcss-html` cannot load |
+
+## Sample output
+
+```
+frontend-syntax: 3 problem(s) in 2 file(s) from 3 declared input(s):
+  dist/**/*.html: the declared input matches no file
+  src/layouts/Base.astro:4:15 Disallowed property "user-select" for selector "body". Leave text selectable across the page, and turn selection off only on the control that needs it.
+  src/styles/site.css:1:17 Disallowed value "all 200ms" for property "transition". Name the properties the transition animates.
+```
+
+A passing run counts what it judged:
+
+```
+frontend-syntax: no violation in 2 file(s) from 2 declared input(s)
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks `frontend-syntax.json` at its root.
+A repository without that file never runs it and needs neither stylelint nor `postcss-html`.
+
+## Related topics
+
+- [checks-browser](checks-browser.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-lint.md

@@ -12,6 +12,7 @@ It runs the gates under [What runs](../../README.md#what-runs), each in its own
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
 `checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
+`checks-frontend-syntax` begins running when the repository tracks `frontend-syntax.json` at its root.
 All other gates run for every repository.
 
 ## What it reads
@@ -46,7 +47,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 13 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 14 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->
@@ -55,6 +56,7 @@ checks-lint: 1 of 13 gate(s) failed: checks-comment-gate
 
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
 It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
+It never runs `checks-browser`, which a product runs after it builds its site.
 
 ## Related topics
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.34.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/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;
+});