@avi2dg/checks 0.47.0 → 0.48.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.48.1
+
+Released 2026-10-20.
+
+### Fixes
+
+- **quality:** hold font shorthand and local size custom properties to the tokens option [#185](https://github.com/avi2d/checks/pull/185)
+- **testing:** compare checks-night-run against the latest night that recorded scores [#184](https://github.com/avi2d/checks/pull/184)
+- **testing:** default checks-test --parallel to the machine's core count [#182](https://github.com/avi2d/checks/pull/182)
+
+## 0.48.0
+
+Released 2026-10-19.
+
+### Features
+
+- **quality:** add opt-in BEM, flat selector and page :has stylelint options [#179](https://github.com/avi2d/checks/pull/179)
+
 ## 0.47.0
 
 Released 2026-10-19.

package/README.md

@@ -223,6 +223,25 @@ To move a repository to a newer release of the kit:
 The repository's lockfile pins the kit, so a repository moves only when it runs these steps.
 [CHANGELOG.md](CHANGELOG.md), shipped in the package, lists what each release changed.
 
+## Turn on the CSS families a repository needs
+
+A repository that declares `frontend-syntax.json` writes `stylelint.config.ts` with the families it needs:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/stylelint";
+
+export default defineConfig({
+  baseline: "widely",
+  tokens: ["src/styles/tokens.css"],
+  bem: true,
+  flatSelectors: true,
+  noPageHas: true,
+});
+```
+
+[checks-frontend-syntax](docs/gates/checks-frontend-syntax.md#what-it-reads) says what each key takes and which family it turns on.
+`noPageHas` sees a `:has` nested under a page selector only together with `flatSelectors`, which refuses the nesting.
+
 ## Where things are
 
 Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.

package/dist/presets/stylelint.d.ts

@@ -4,7 +4,10 @@ export type BaselineTarget = "widely" | "newly" | number;
 export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
     readonly baseline: BaselineTarget;
     readonly tokens: Globs | false;
+    readonly bem?: boolean;
+    readonly flatSelectors?: boolean;
+    readonly noPageHas?: boolean;
 };
 export declare const MARKUP: readonly ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
-export declare function defineConfig({ baseline, tokens, rules, overrides, ...rest }: ChecksStylelintConfig): Config;
+export declare function defineConfig({ baseline, tokens, bem, flatSelectors, noPageHas, rules, overrides, ...rest }: ChecksStylelintConfig): Config;
 export {};

package/dist/presets/stylelint.js

@@ -20,11 +20,92 @@ var LANGUAGE_FREE_SELECTORS = {
   "selector-disallowed-list": ["/[^\\x00-\\x7F]/"]
 };
 var COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"];
+var BEM_NAMES = {
+  "selector-class-pattern": "^[a-z][a-z0-9]*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$"
+};
+var POSITIONAL_PSEUDO_CLASSES = [
+  "first-child",
+  "last-child",
+  "only-child",
+  "nth-child",
+  "nth-last-child",
+  "first-of-type",
+  "last-of-type",
+  "only-of-type",
+  "nth-of-type",
+  "nth-last-of-type"
+];
+var FLAT_SELECTORS = {
+  "selector-max-type": 0,
+  "selector-max-id": 0,
+  "selector-max-universal": 0,
+  "selector-max-compound-selectors": 2,
+  "max-nesting-depth": 0,
+  "selector-max-attribute": 0,
+  "selector-pseudo-class-disallowed-list": POSITIONAL_PSEUDO_CLASSES
+};
+var PAGE_HAS = "/^(?=[\\s\\S]*:has\\()(?=[\\s\\S]*(?:(?:^|[\\s>+~,([])(?:html|body|main)|:root)(?![\\w-]))[\\s\\S]*$/i";
+var PSEUDO_ARGUMENT = "(?:[^()]|\\([^()]*\\))*";
+var PSEUDO_CLASS = `::?[\\w-]+(?:\\(${PSEUDO_ARGUMENT}\\))?`;
+var HAS_IN_PSEUDO_CLASS = `(?::has\\(${PSEUDO_ARGUMENT}\\)|::?[\\w-]+\\(${PSEUDO_ARGUMENT}:has\\([^()]*\\)${PSEUDO_ARGUMENT}\\))`;
+var CLASSLESS_HAS = `/(?:^|[\\s>+~,])(?:${PSEUDO_CLASS})*${HAS_IN_PSEUDO_CLASS}(?:${PSEUDO_CLASS})*(?=[\\s>+~,]|$)/i`;
+var VAR = "var\\(\\s*--[^\\s,()]+\\s*\\)";
+var VAR_NAMES = /var\(\s*(--[^\s,()]+)\s*\)/gi;
+var FONT_SIZE_VALUE = new RegExp(`^${VAR}$`, "i");
+var FONT_STYLE_VARIANT_WEIGHT_OR_WIDTH = "(?:normal|italic|oblique(?:\\s+-?[\\d.]+(?:deg|grad|rad|turn))?|small-caps|bold|bolder|lighter|[1-9]\\d*(?:\\.\\d+)?|(?:ultra-|extra-|semi-)?(?:condensed|expanded))";
+var FONT_FAMILY = `(?:"[^"]*"|'[^']*'|${VAR}|-?[a-z_][\\w-]*(?:\\s+-?[a-z_][\\w-]*)*)`;
+var FONT_FAMILIES = `${FONT_FAMILY}(?:\\s*,\\s*${FONT_FAMILY})*`;
+var FONT_FAMILY_VALUE = new RegExp(`^${FONT_FAMILIES}$`, "i");
+var FONT_VALUE = new RegExp(`^(?:${FONT_STYLE_VARIANT_WEIGHT_OR_WIDTH}\\s+)*(?<size>${VAR})(?:\\s*\\/\\s*(?:${VAR}|[\\w.%-]+))?(?:\\s+(?<families>${FONT_FAMILIES}))?$`, "i");
+var FONT_SIZE_RULE = "checks/font-size-from-tokens";
+function varNames(value) {
+  return [...value.matchAll(VAR_NAMES)].map(([, name]) => name).filter((name) => name !== undefined);
+}
+function sizeCarriers(property, value) {
+  const name = property.toLowerCase();
+  if (name === "font-size" && FONT_SIZE_VALUE.test(value))
+    return varNames(value).map((token) => ({ token, setTo: FONT_SIZE_VALUE }));
+  const font = name === "font" ? FONT_VALUE.exec(value)?.groups : undefined;
+  if (font?.size === undefined)
+    return [];
+  return [
+    ...varNames(font.size).map((token) => ({ token, setTo: FONT_SIZE_VALUE })),
+    ...varNames(font.families ?? "").map((token) => ({ token, setTo: FONT_FAMILY_VALUE }))
+  ];
+}
+function fromTokens({ token, setTo }, declared, seen) {
+  const values = declared.get(token);
+  if (values === undefined)
+    return true;
+  return values.every((value) => setTo.test(value) && varNames(value).every((alias) => !seen.has(alias) && fromTokens({ token: alias, setTo }, declared, new Set([...seen, alias]))));
+}
+var fontSizeFromTokens = () => async (root, result) => {
+  const { utils } = (await import("stylelint")).default;
+  const declared = new Map;
+  result.root.walkDecls(/^--/, ({ prop, value }) => {
+    declared.set(prop, [...declared.get(prop) ?? [], value]);
+  });
+  root.walkDecls((node) => {
+    for (const carrier of sizeCarriers(node.prop, node.value)) {
+      if (fromTokens(carrier, declared, new Set([carrier.token])))
+        continue;
+      utils.report({ ruleName: FONT_SIZE_RULE, result, node, word: carrier.token, message: `Expected "${carrier.token}" from the token files rather than set in this file` });
+    }
+  });
+};
+var FONT_SIZE_PLUGIN = {
+  ruleName: FONT_SIZE_RULE,
+  rule: Object.assign(fontSizeFromTokens, { ruleName: FONT_SIZE_RULE, messages: {} })
+};
 var DESIGN_TOKENS = {
   "color-no-hex": true,
   "color-named": "never",
   "function-disallowed-list": COLOUR_FUNCTIONS.map((name) => `/^${name}$/i`),
-  "declaration-property-value-allowed-list": { "/^font-size$/i": ["/^var\\(\\s*--[^\\s,()]+\\s*\\)$/i", "/^inherit$/i"] }
+  "declaration-property-value-allowed-list": {
+    "/^font-size$/i": [String(FONT_SIZE_VALUE), "/^inherit$/i"],
+    "/^font$/i": [String(FONT_VALUE), "/^inherit$/i"]
+  },
+  [FONT_SIZE_RULE]: true
 };
 var REFUSED_BASELINE = '@avi2dg/checks/stylelint: set baseline to "widely", "newly" or a year such as 2024';
 var REFUSED_TOKENS = "@avi2dg/checks/stylelint: set tokens to the globs of the token files, or false to leave the design token rules off";
@@ -61,22 +142,29 @@ function designTokens(files) {
   const off = Object.fromEntries(Object.keys(DESIGN_TOKENS).map((rule) => [rule, null]));
   return { rules: DESIGN_TOKENS, overrides: [{ files: [...files], rules: off }] };
 }
-function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }) {
+function disallowedSelectors(noPageHas) {
+  if (noPageHas === true)
+    return { "selector-disallowed-list": [[...LANGUAGE_FREE_SELECTORS["selector-disallowed-list"], PAGE_HAS, CLASSLESS_HAS], { splitList: true }] };
+  return LANGUAGE_FREE_SELECTORS;
+}
+function defineConfig({ baseline, tokens, bem, flatSelectors, noPageHas, rules, overrides = [], ...rest }) {
   const available = baselineTarget(baseline);
   const tokenRules = designTokens(tokenFiles(tokens));
   const merged = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
     ...COMMENT_REFUSAL,
-    ...LANGUAGE_FREE_SELECTORS,
+    ...disallowedSelectors(noPageHas),
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
+    ...bem === true ? BEM_NAMES : null,
+    ...flatSelectors === true ? FLAT_SELECTORS : null,
     ...rules
   };
   return {
     ...rest,
     extends: [peer("stylelint-config-standard")],
-    plugins: [peer("stylelint-plugin-use-baseline")],
+    plugins: [peer("stylelint-plugin-use-baseline"), FONT_SIZE_PLUGIN],
     rules: { ...merged, [BASELINE_RULE]: passProperty(merged[BASELINE_RULE]) },
     overrides: [
       { files: [...MARKUP], customSyntax: peer("postcss-html") },

package/docs/configs/native-settings.md

@@ -17,7 +17,7 @@ A consuming repository puts each setting in the file its tool reads, and no mani
 | `exports-baseline.json` | The existing unused exports and types, per file, kind and name | `checks-exports` |
 | `.jscpd.json` | The `path` and `ignore` globs of the files repetition is measured in | jscpd and `checks-repetition` |
 | `knip.config.ts` | The `entry` globs Knip traces unreferenced files from | Knip, `checks-unused` and `checks-exports` |
-| `stylelint.config.ts` | The Baseline target, the token files, and any stylelint rule the repository sets over the kit's families | `checks-frontend-syntax` |
+| `stylelint.config.ts` | The Baseline target, the token files, the CSS families the repository turns on, and any stylelint rule the repository sets over the kit's families | `checks-frontend-syntax` |
 | `dependency-cruiser.config.ts` | Entry points nothing imports, paths that may import dev dependencies, and import boundaries, when the kit's defaults do not fit | `checks-imports` |
 | `tsconfig.json` | Compiler options, and the Effect language service plugin whose `overrides` and kit severities `checks-effect-scope` writes, keeping every other key | TypeScript and Effect language service |
 | `package.json` | `scripts` with the `checks-vendor` arguments in `prepare`, `author` and `contributors` | Bun, `checks-commit-identity` and `checks-vendor` |
@@ -41,7 +41,7 @@ The builder throws when the tool loads such a config anyway.
 | `@avi2dg/checks/oxlint` | `effect` | `extends`, `plugins`, `jsPlugins` and `categories` |
 | `@avi2dg/checks/knip` | `entry`, where `[]` means the package scripts and tests name every entry | `include` |
 | `@avi2dg/checks/dependency-cruiser` | nothing | `extends` |
-| `@avi2dg/checks/stylelint` | `baseline` and `tokens`, where `false` leaves the design token rules off | `extends` and `plugins` |
+| `@avi2dg/checks/stylelint` | `baseline` and `tokens`, where `false` leaves the design token rules off, with `bem`, `flatSelectors` and `noPageHas` turning on their families | `extends` and `plugins` |
 
 A repository whose sources are Effect programs writes `oxlint.config.ts`:
 

package/docs/design.md

@@ -305,10 +305,10 @@ A browser check needs a built site and a browser, and a backend repository has n
 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.
+Each check wraps a detector that already works, and the kit writes a rule of its own only where none decides the constraint.
 The syntax gate runs two of stylelint's built-in rules and the stylelint team's shared configs, `axe` runs axe-core and `nesting` runs one html-validate rule.
 Its Baseline family runs `stylelint-plugin-use-baseline`, the one stylelint rule that judges against the Baseline data rather than a browser list.
-Its design token family is stylelint's own colour and value rules, applied outside the files a repository names as its tokens.
+Its design token family is stylelint's own colour and value rules and the kit's `checks/font-size-from-tokens`, applied outside the files a repository names as its tokens.
 A check of the rendered page against declared tokens would need a token format of the kit's own.
 The repository's `stylelint.config.ts` sets the Baseline target and the token files, since only the repository knows either.
 The gate imports that file itself, because stylelint's config loader calls `typescript.findConfigFile`, which TypeScript 7 lacks, and a JavaScript config is what [checks-no-plain-js](gates/checks-no-plain-js.md) refuses.

package/docs/gates/checks-flake.md

@@ -15,8 +15,10 @@ A run that fails with no failing test, such as a test file that throws while loa
 
 ## Parallel hunts
 
-A repository whose `test` script passes `--parallel=<workers>` to [checks-test](checks-test.md#parallel-runs) is hunted with the same worker count, so each run is `bun test --randomize --seed=<seed> --parallel=<workers>`, the mode CI runs in.
-A `test` script without the option keeps the serial hunt.
+A repository whose `test` script runs [checks-test](checks-test.md#parallel-runs) is hunted with the worker count `checks-test` runs on.
+That is the `--parallel=<workers>` the script passes, or else one worker per core of the machine.
+So each run is `bun test --randomize --seed=<seed> --parallel=<workers>`, the mode CI runs in.
+A `test` script that does not run `checks-test` gets the serial hunt.
 
 Under workers a seed fixes the order Bun hands out the files.
 Which worker takes each file is a race between the workers.
@@ -42,7 +44,8 @@ A run whose worker crashed gets a replay of that worker's files up to the crashe
 ## What it reads
 
 It reads bun's JUnit report of each run.
-It reads the worker count from the `test` script in `package.json`, as [checks-test-layout](checks-test-layout.md) validates that script, and hunts serially when the file is missing.
+It reads the worker count from the `test` script in `package.json`, as [checks-test-layout](checks-test-layout.md) validates that script.
+It hunts serially when the file is missing or its `test` script does not run `checks-test`.
 Under workers it reads the record its preload writes of which worker ran each file.
 For each replay it reads the order Bun ran its placeholder files.
 Under GitHub Actions it appends its summary to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.

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

@@ -37,16 +37,20 @@ A control that needs selection off sets it on its own selector, such as `.drag-h
 | G1 correctness | `stylelint-config-recommended`, the stylelint team's rules for likely mistakes, such as `font-variant-numeric: oldstyle-num` for `oldstyle-nums` | on |
 | G2 conventions | `stylelint-config-standard`, which extends G1 with the stylelint team's notation and spacing rules | on |
 | G3 selector complexity | `selector-max-specificity` at `0,3,2` and `selector-max-compound-selectors` at 3 | on |
-| G4 design tokens | `color-no-hex`, `color-named: "never"`, `function-disallowed-list` over `rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch` and `color`, and `font-size` only as one `var(--…)` with no fallback, or `inherit` | off until `tokens` names the token files, and off in those files |
+| G4 design tokens | `color-no-hex`, `color-named: "never"`, `function-disallowed-list` over `rgb`, `rgba`, `hsl`, `hsla`, `hwb`, `lab`, `lch`, `oklab`, `oklch` and `color`, `font-size` only as one `var(--…)` with no fallback, or `inherit`, `font` only as `inherit`, or as such a `var(--…)` for its size after any literal style, variant, weight or width, and before an optional line height and a family list of names, strings and `var(--…)`s, and `checks/font-size-from-tokens`, which refuses a `var(--…)` for a size or a family naming a custom property that any style block or attribute of the same file sets, unless the file sets it only to another such `var(--…)`, or for a family to a family list | off until `tokens` names the token files, and off in those files |
 | G5 Baseline target | `plugin/use-baseline` from `stylelint-plugin-use-baseline`, which judges each property, value, function, at-rule, selector and unit against the Baseline data, and passes a property inside an `@supports` block. It passes `@property` at every target, since a browser without `@property` treats the declaration as an unregistered custom property | on, at the target `baseline` sets |
 | G6 comments refused | `comment-word-disallowed-list` over `/^[\s\S]*$/`, which refuses every comment, including an empty `/* */` | on |
 | G7 language-free selectors | `selector-disallowed-list` over `/[^\x00-\x7F]/`, which refuses any selector holding a non-ASCII character, in attribute values, class names and ids alike | on |
+| G8 BEM names | `selector-class-pattern` over one lowercase block with kebab `__element` and `--modifier` parts | off until `bem` is `true` |
+| G9 class-only flat selectors | `selector-max-type` at 0, `selector-max-id` at 0, `selector-max-universal` at 0, `selector-max-compound-selectors` at 2, `max-nesting-depth` at 0, `selector-max-attribute` at 0, and `selector-pseudo-class-disallowed-list` over the positional pseudo-classes, from `:first-child` to `:nth-last-of-type` | off until `flatSelectors` is `true` |
+| G10 page-wide has refused | `selector-disallowed-list` with `splitList` over a pattern that refuses a `:has` beside `html`, `body`, `main` or `:root` in one selector of a list, across line breaks in the selector, and one that refuses a `:has` in a compound of pseudo-classes alone, such as `:has(.hero)`, `:scope:has(.hero)` or `:not(.card):has(.hero)`, whose subject can be the root. A nested `:has` escapes it unless G9 refuses the nesting | off until `noPageHas` is `true` |
 
-The builder changes three of the shared config's rules:
+The builder changes four of the shared config's rules:
 
 - `no-descending-specificity` is off, since it compares only the last compound selector and has no access to the DOM.
   It reports components that never match one element.
 - `property-no-vendor-prefix` keeps reporting without a fix, and passes `-webkit-user-select`, since its fix deletes the prefix Safari still needs.
+- `selector-class-pattern` holds BEM names while `bem` is `true`, since the shared kebab case refuses `__` and `--`.
 - In an `.html` or `.astro` file, `declaration-block-single-line-max-declarations` is off, since a `style` attribute is one line.
 
 The comment rule refuses every comment but a sourcemap `/*# */` one, which stylelint passes to keep the map.
@@ -70,6 +74,7 @@ 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)`, a style a script sets, or a colour a build writes into CSS outside the declared inputs.
+- A font size custom property that one stylesheet outside the token files sets and another reads.
 - `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.
@@ -108,6 +113,9 @@ The builder throws when the gate loads such a config anyway.
 | --- | --- |
 | `baseline` | `"widely"`, `"newly"` or a year such as `2024`, which allows what became Baseline newly available in that year or earlier |
 | `tokens` | the globs of the files that declare the design tokens, which turns G4 on in every other file, or `false` |
+| `bem` | `true` to turn G8 on, left out to leave it off |
+| `flatSelectors` | `true` to turn G9 on, left out to leave it off |
+| `noPageHas` | `true` to turn G10 on, left out to leave it off |
 
 `rules`, `overrides`, `ignoreFiles` and the other keys mean what they mean in stylelint's own docs, and land after the kit's.
 An accepted exception lives there rather than in a comment, such as a property the Baseline rule passes:

package/docs/gates/checks-night-run.md

@@ -44,8 +44,10 @@ A run on any ref but `refs/heads/main` files no issue and records no score, and
 ## What it reads
 
 It reads tonight's Stryker `mutation.json` report, when the mutation run left one, and any number of JUnit reports, such as the ones `checks-test --junit=<file>` keeps, as [checks-test](checks-test.md#arguments) says.
-It reads the previous night from the `night-run` artifact of the newest successful run of the same workflow on `main`.
-That artifact holds `night-run.json`, the scores the run recorded, and a newest run without it counts as no previous night.
+It scans the newest 30 successful runs of the same workflow on `main` from newest to oldest.
+It takes the first run whose `night-run` artifact still exists as the previous night.
+That artifact holds `night-run.json`, the scores the run recorded.
+When no scanned run holds the artifact it compares no score.
 A run on another branch never becomes the previous night.
 On `main` with a mutation report it writes tonight's scores to `reports/night-run.json`, and the workflow uploads that file as the `night-run` artifact.
 It reads the run from `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `GITHUB_RUN_ID`, `GITHUB_WORKFLOW_REF` and `GITHUB_REF`, so it runs only inside a GitHub Actions job.

package/docs/gates/checks-test-layout.md

@@ -26,7 +26,7 @@ It fails unless the repository holds this shape, and names the file and the path
   It may not import `$`, `spawn`, `spawnSync`, `connect`, `serve` or `listen` from `bun`, may not touch `Bun.$` or `Bun.spawn`, and may not call `fetch`.
   A test at the `e2e`, `live` or `pixel` level may do all of it, under `tests/quarantine/` as well.
   Helpers in `tests/lib/**` answer to the same rule, since an in-process test reaches them.
-- `scripts.test` is `checks-test`, optionally with `--parallel=<workers>`, which runs `bun test --randomize` as [checks-test](checks-test.md) says.
+- `scripts.test` is `checks-test`, optionally with `--parallel=<workers>`, which runs `bun test --randomize --parallel=<workers>` as [checks-test](checks-test.md#parallel-runs) says.
 - `scripts.lint` runs this check, itself or through `checks-lint` called by its bare bin name.
 - `bunfig.toml` carries every `[test]` key of the shipped preset with the same value.
   `[test].pathIgnorePatterns` is the preset's `["**/tests/quarantine/**", "**/tests/live/**", "**/tests/pixel/**", "repos/**"]`, which the check pins itself, so the kit's own repository, whose bunfig is the preset, cannot drift it either.

package/docs/gates/checks-test.md

@@ -8,7 +8,7 @@ audience: consumers
 
 ## What it checks
 
-It runs the default suite with `bun test --randomize` and reads Bun's JUnit report from that run.
+It runs the default suite with `bun test --randomize --parallel=<workers>`, as [Parallel runs](#parallel-runs) says, and reads Bun's JUnit report from that run.
 It runs Bun with `CI=true`, so `test.only` fails the run in every environment.
 Bun exits zero when tests skip, so `checks-test` checks every skipped test against its source declaration.
 A test that `test.skip`, `test.skipIf`, `test.if`, `test.todo` or an enclosing `describe.skip` skips fails unless the test declares its reason.
@@ -76,7 +76,9 @@ Bun ignores both directories during the default run.
 
 ## Parallel runs
 
-A repository runs its test files in parallel by passing a worker count in its `test` script:
+`checks-test` runs `bun test --randomize --parallel=<workers>`, so Bun hands each test file to one of that many worker processes.
+Without `--parallel=<workers>`, the count is one worker per core, as `os.availableParallelism()` reports it, so a local run never oversubscribes the machine.
+A repository sets its own count by passing `--parallel=<workers>` in its `test` script:
 
 ```json
 {
@@ -86,13 +88,12 @@ A repository runs its test files in parallel by passing a worker count in its `t
 }
 ```
 
-`checks-test --parallel=<workers>` runs `bun test --randomize --parallel=<workers>`, so Bun hands each test file to one of that many worker processes.
-Each file then runs in a fresh global, so a file cannot lean on state another file left behind.
-The count is a whole number from 1 up, and without the option the suite runs serially in one process.
+The count is a whole number from 1 up.
+Each file runs in a fresh global, so a file cannot lean on state another file left behind.
 Tests still run in random order, and `test.only` still fails the run.
-Bun merges every worker's results into the one JUnit report, so each skipped test and each todo is judged as in a serial run.
+Bun merges every worker's results into the one JUnit report, so each skipped test and each todo is judged across the whole suite.
 A tier script takes the same option, as in `checks-test --tier=live --parallel=4`.
-[checks-flake](checks-flake.md#parallel-hunts) hunts with the worker count the `test` script sets.
+[checks-flake](checks-flake.md#parallel-hunts) hunts with the same worker count.
 
 A file whose worker crashes, for example when a test calls `process.exit`, fails the run.
 Bun reports no result from that file, so its skips are not judged and its declarations are not reported as stale.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.47.0",
+  "version": "0.48.1",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -180,10 +180,11 @@
   },
   "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",
-    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/testing/mutation-guard-plugin.ts src/testing/mutation-refusal.ts --outdir dist/mutation --target node --format esm && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts src/quality/presets/stylelint.ts --outdir dist/presets --target node --format esm && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/testing/mutation-guard-plugin.ts src/testing/mutation-refusal.ts --outdir dist/mutation --target node --format esm && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts src/quality/presets/stylelint.ts --outdir dist/presets --target node --format esm --packages external && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint && bun src/core/lint.ts",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun src/testing/test.ts",
+    "test:fast": "bun scripts/test-fast.ts",
     "test:unit": "bun src/testing/test.ts --tier=unit",
     "test:e2e": "bun src/testing/test.ts --tier=e2e --parallel=4",
     "mutate": "bunx stryker run",

package/src/quality/presets/stylelint.ts

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import type { Config } from "stylelint";
+import type { Config, Plugin, RuleBase } from "stylelint";
 
 type Globs = readonly [string, ...string[]];
 
@@ -8,6 +8,9 @@ export type BaselineTarget = "widely" | "newly" | number;
 export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
   readonly baseline: BaselineTarget;
   readonly tokens: Globs | false;
+  readonly bem?: boolean;
+  readonly flatSelectors?: boolean;
+  readonly noPageHas?: boolean;
 };
 
 type Rules = NonNullable<Config["rules"]>;
@@ -43,11 +46,124 @@ const LANGUAGE_FREE_SELECTORS = {
 
 const COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"] as const;
 
+// selector-class-pattern builds a RegExp from the string itself, so slashes would match literal slashes.
+const BEM_NAMES = {
+  "selector-class-pattern": "^[a-z][a-z0-9]*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$",
+} as const satisfies Rules;
+
+const POSITIONAL_PSEUDO_CLASSES = [
+  "first-child",
+  "last-child",
+  "only-child",
+  "nth-child",
+  "nth-last-child",
+  "first-of-type",
+  "last-of-type",
+  "only-of-type",
+  "nth-of-type",
+  "nth-last-of-type",
+] as const;
+
+const FLAT_SELECTORS = {
+  "selector-max-type": 0,
+  "selector-max-id": 0,
+  "selector-max-universal": 0,
+  "selector-max-compound-selectors": 2,
+  "max-nesting-depth": 0,
+  "selector-max-attribute": 0,
+  "selector-pseudo-class-disallowed-list": POSITIONAL_PSEUDO_CLASSES,
+} as const satisfies Rules;
+
+// The ban needs both a page element and :has( in one selector, in either order, and a class such as .block-body holds neither.
+// The rule tests the raw selector, newlines included, so [\s\S] stands where . would stop at a line break.
+const PAGE_HAS = "/^(?=[\\s\\S]*:has\\()(?=[\\s\\S]*(?:(?:^|[\\s>+~,([])(?:html|body|main)|:root)(?![\\w-]))[\\s\\S]*$/i";
+
+const PSEUDO_ARGUMENT = "(?:[^()]|\\([^()]*\\))*";
+
+const PSEUDO_CLASS = `::?[\\w-]+(?:\\(${PSEUDO_ARGUMENT}\\))?`;
+
+const HAS_IN_PSEUDO_CLASS = `(?::has\\(${PSEUDO_ARGUMENT}\\)|::?[\\w-]+\\(${PSEUDO_ARGUMENT}:has\\([^()]*\\)${PSEUDO_ARGUMENT}\\))`;
+
+// A compound of pseudo-classes alone, :scope and :not(.card) among them, can match the root element, so its :has() reads page state.
+const CLASSLESS_HAS = `/(?:^|[\\s>+~,])(?:${PSEUDO_CLASS})*${HAS_IN_PSEUDO_CLASS}(?:${PSEUDO_CLASS})*(?=[\\s>+~,]|$)/i`;
+
+const VAR = "var\\(\\s*--[^\\s,()]+\\s*\\)";
+
+const VAR_NAMES = /var\(\s*(--[^\s,()]+)\s*\)/gi;
+
+const FONT_SIZE_VALUE = new RegExp(`^${VAR}$`, "i");
+
+const FONT_STYLE_VARIANT_WEIGHT_OR_WIDTH = "(?:normal|italic|oblique(?:\\s+-?[\\d.]+(?:deg|grad|rad|turn))?|small-caps|bold|bolder|lighter|[1-9]\\d*(?:\\.\\d+)?|(?:ultra-|extra-|semi-)?(?:condensed|expanded))";
+
+const FONT_FAMILY = `(?:"[^"]*"|'[^']*'|${VAR}|-?[a-z_][\\w-]*(?:\\s+-?[a-z_][\\w-]*)*)`;
+
+const FONT_FAMILIES = `${FONT_FAMILY}(?:\\s*,\\s*${FONT_FAMILY})*`;
+
+const FONT_FAMILY_VALUE = new RegExp(`^${FONT_FAMILIES}$`, "i");
+
+// A family name or a token name can hold a size word, so the token is required in the size slot rather than size words refused anywhere.
+const FONT_VALUE = new RegExp(
+  `^(?:${FONT_STYLE_VARIANT_WEIGHT_OR_WIDTH}\\s+)*(?<size>${VAR})(?:\\s*\\/\\s*(?:${VAR}|[\\w.%-]+))?(?:\\s+(?<families>${FONT_FAMILIES}))?$`,
+  "i",
+);
+
+const FONT_SIZE_RULE = "checks/font-size-from-tokens";
+
+function varNames(value: string): string[] {
+  return [...value.matchAll(VAR_NAMES)].map(([, name]) => name).filter((name) => name !== undefined);
+}
+
+type SizeCarrier = { readonly token: string; readonly setTo: RegExp };
+
+// A var() before the size var can be a weight, which leaves a family var() free to hold the size.
+function sizeCarriers(property: string, value: string): SizeCarrier[] {
+  const name = property.toLowerCase();
+  if (name === "font-size" && FONT_SIZE_VALUE.test(value)) return varNames(value).map((token) => ({ token, setTo: FONT_SIZE_VALUE }));
+  const font = name === "font" ? FONT_VALUE.exec(value)?.groups : undefined;
+  if (font?.size === undefined) return [];
+  return [
+    ...varNames(font.size).map((token) => ({ token, setTo: FONT_SIZE_VALUE })),
+    ...varNames(font.families ?? "").map((token) => ({ token, setTo: FONT_FAMILY_VALUE })),
+  ];
+}
+
+function fromTokens({ token, setTo }: SizeCarrier, declared: ReadonlyMap<string, readonly string[]>, seen: ReadonlySet<string>): boolean {
+  const values = declared.get(token);
+  if (values === undefined) return true;
+  return values.every(
+    (value) => setTo.test(value) && varNames(value).every((alias) => !seen.has(alias) && fromTokens({ token: alias, setTo }, declared, new Set([...seen, alias]))),
+  );
+}
+
+// postcss-html hands the rule one root per style block or attribute, so the file's declarations sit on the result's document.
+const fontSizeFromTokens: RuleBase = () => async (root, result) => {
+  const { utils } = (await import("stylelint")).default;
+  const declared = new Map<string, string[]>();
+  result.root.walkDecls(/^--/, ({ prop, value }) => {
+    declared.set(prop, [...(declared.get(prop) ?? []), value]);
+  });
+  root.walkDecls((node) => {
+    for (const carrier of sizeCarriers(node.prop, node.value)) {
+      if (fromTokens(carrier, declared, new Set([carrier.token]))) continue;
+      utils.report({ ruleName: FONT_SIZE_RULE, result, node, word: carrier.token, message: `Expected "${carrier.token}" from the token files rather than set in this file` });
+    }
+  });
+};
+
+const FONT_SIZE_PLUGIN = {
+  ruleName: FONT_SIZE_RULE,
+  rule: Object.assign(fontSizeFromTokens, { ruleName: FONT_SIZE_RULE, messages: {} }),
+} satisfies Plugin;
+
 const DESIGN_TOKENS = {
   "color-no-hex": true,
   "color-named": "never",
   "function-disallowed-list": COLOUR_FUNCTIONS.map((name) => `/^${name}$/i`),
-  "declaration-property-value-allowed-list": { "/^font-size$/i": ["/^var\\(\\s*--[^\\s,()]+\\s*\\)$/i", "/^inherit$/i"] },
+  "declaration-property-value-allowed-list": {
+    "/^font-size$/i": [String(FONT_SIZE_VALUE), "/^inherit$/i"],
+    "/^font$/i": [String(FONT_VALUE), "/^inherit$/i"],
+  },
+  [FONT_SIZE_RULE]: true,
 } as const satisfies Rules;
 
 const REFUSED_BASELINE = '@avi2dg/checks/stylelint: set baseline to "widely", "newly" or a year such as 2024';
@@ -87,23 +203,30 @@ function designTokens(files: readonly string[]): Required<Pick<Config, "rules" |
   return { rules: DESIGN_TOKENS, overrides: [{ files: [...files], rules: off }] };
 }
 
+function disallowedSelectors(noPageHas: boolean | undefined): Rules {
+  if (noPageHas === true) return { "selector-disallowed-list": [[...LANGUAGE_FREE_SELECTORS["selector-disallowed-list"], PAGE_HAS, CLASSLESS_HAS], { splitList: true }] };
+  return LANGUAGE_FREE_SELECTORS;
+}
+
 // The types refuse a missing or malformed baseline or tokens, and the guards repeat it for a config no typecheck reads.
-export function defineConfig({ baseline, tokens, rules, overrides = [], ...rest }: ChecksStylelintConfig): Config {
+export function defineConfig({ baseline, tokens, bem, flatSelectors, noPageHas, rules, overrides = [], ...rest }: ChecksStylelintConfig): Config {
   const available = baselineTarget(baseline);
   const tokenRules = designTokens(tokenFiles(tokens));
   const merged: Rules = {
     ...CONVENTION_CHANGES,
     ...SELECTOR_COMPLEXITY,
     ...COMMENT_REFUSAL,
-    ...LANGUAGE_FREE_SELECTORS,
+    ...disallowedSelectors(noPageHas),
     [BASELINE_RULE]: [true, { available }],
     ...tokenRules.rules,
+    ...(bem === true ? BEM_NAMES : null),
+    ...(flatSelectors === true ? FLAT_SELECTORS : null),
     ...rules,
   };
   return {
     ...rest,
     extends: [peer("stylelint-config-standard")],
-    plugins: [peer("stylelint-plugin-use-baseline")],
+    plugins: [peer("stylelint-plugin-use-baseline"), FONT_SIZE_PLUGIN],
     rules: { ...merged, [BASELINE_RULE]: passProperty(merged[BASELINE_RULE]) },
     overrides: [
       { files: [...MARKUP], customSyntax: peer("postcss-html") },

package/src/testing/flake.ts

@@ -3,7 +3,7 @@ import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } fro
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
-import { scriptOptions } from "./test.ts";
+import { scriptOptions, workerCount } from "./test.ts";
 
 export type Run = {
   readonly seed: number;
@@ -90,7 +90,8 @@ const workersOf = Effect.fn("workersOf")(function* (root: string) {
     Effect.flatMap(decodeManifest),
     Effect.mapError((cause) => new ManifestError({ message: `cannot read ${file}: ${cause.message}` })),
   );
-  return scriptOptions(scripts?.["test"])?.workers;
+  const options = scriptOptions(scripts?.["test"]);
+  return options === undefined ? undefined : workerCount(options.workers);
 });
 
 const assignmentOf = Effect.fn("assignmentOf")(function* (log: string) {

package/src/testing/night-run.ts

@@ -175,24 +175,26 @@ const decodeRecord = Schema.decodeUnknownEffect(Schema.fromJsonString(NightRecor
 
 const unreadable = (source: string) => (cause: { readonly message: string }) => new NightRunFailure({ message: `cannot read ${source}: ${cause.message}` });
 
-// Only the newest successful run on main counts, so a branch dispatch never becomes the night a later run compares with.
+// A skipped night records no artifact, so the newest successful run can carry no baseline.
 const previousNight = Effect.fn("previousNight")(
   function* ({ runs, workflow }: Actions) {
-    const listed = ["run", "list", "--workflow", workflow, "--branch", DEFAULT_BRANCH, "--status", "success", "--limit", "1", "--json", "databaseId,event,createdAt"];
-    const [newest] = yield* gh(listed).pipe(Effect.flatMap(decodeRuns), Effect.mapError(unreadable(`the runs of ${workflow}`)));
-    if (newest === undefined) return Option.none<PreviousNight>();
-    const run = newest.databaseId;
-    const { artifacts } = yield* gh(["api", `${REPOSITORY}/actions/runs/${run}/artifacts?name=${ARTIFACT}`]).pipe(
-      Effect.flatMap(decodeArtifacts),
-      Effect.mapError(unreadable(`the artifacts of run ${run}`)),
-    );
-    if (!artifacts.some((artifact) => artifact.name === ARTIFACT && !artifact.expired)) return Option.none<PreviousNight>();
-    const fs = yield* FileSystem.FileSystem;
-    const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-night-run-" });
-    yield* gh(["run", "download", String(run), "--name", ARTIFACT, "--dir", dir]);
-    const file = (yield* Path.Path).join(dir, RECORD_NAME);
-    const record = yield* fs.readFileString(file).pipe(Effect.flatMap(decodeRecord), Effect.mapError(unreadable(`the ${ARTIFACT} artifact of run ${run}`)));
-    return Option.some<PreviousNight>({ url: `${runs}/${run}`, record });
+    const listed = ["run", "list", "--workflow", workflow, "--branch", DEFAULT_BRANCH, "--status", "success", "--limit", "30", "--json", "databaseId,event,createdAt"];
+    const candidates = yield* gh(listed).pipe(Effect.flatMap(decodeRuns), Effect.mapError(unreadable(`the runs of ${workflow}`)));
+    for (const candidate of candidates) {
+      const run = candidate.databaseId;
+      const { artifacts } = yield* gh(["api", `${REPOSITORY}/actions/runs/${run}/artifacts?name=${ARTIFACT}`]).pipe(
+        Effect.flatMap(decodeArtifacts),
+        Effect.mapError(unreadable(`the artifacts of run ${run}`)),
+      );
+      if (!artifacts.some((artifact) => artifact.name === ARTIFACT && !artifact.expired)) continue;
+      const fs = yield* FileSystem.FileSystem;
+      const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-night-run-" });
+      yield* gh(["run", "download", String(run), "--name", ARTIFACT, "--dir", dir]);
+      const file = (yield* Path.Path).join(dir, RECORD_NAME);
+      const record = yield* fs.readFileString(file).pipe(Effect.flatMap(decodeRecord), Effect.mapError(unreadable(`the ${ARTIFACT} artifact of run ${run}`)));
+      return Option.some<PreviousNight>({ url: `${runs}/${run}`, record });
+    }
+    return Option.none<PreviousNight>();
   },
   Effect.scoped,
 );

package/src/testing/test.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { availableParallelism } from "node:os";
 import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { TEST_ENTRY_POINT } from "../core/gates.ts";
@@ -164,10 +165,13 @@ function tierArgs(tier: TestTier | undefined): readonly string[] {
   return [`./tests/${tier}`];
 }
 
+export function workerCount(workers: number | undefined): number {
+  return workers ?? availableParallelism();
+}
+
 const runSuite = Effect.fn("runSuite")(function* (outfile: string, { tier, workers }: TestOptions) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-  const parallelArgs = workers === undefined ? [] : [`--parallel=${workers}`];
-  const args = ["test", "--randomize", ...parallelArgs, ...tierArgs(tier), ...reporterArgs(outfile)];
+  const args = ["test", "--randomize", `--parallel=${workerCount(workers)}`, ...tierArgs(tier), ...reporterArgs(outfile)];
   return yield* spawner.exitCode(
     ChildProcess.make(process.execPath, args, {
       stdin: "ignore",