@avi2dg/checks 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 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,6 +20,35 @@ 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 DESIGN_TOKENS = {
   "color-no-hex": true,
   "color-named": "never",
@@ -61,16 +90,23 @@ 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 {

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/gates/checks-frontend-syntax.md

@@ -41,12 +41,16 @@ A control that needs selection off sets it on its own selector, such as `.drag-h
 | 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.
@@ -108,6 +112,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -184,6 +184,7 @@
     "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

@@ -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,6 +46,47 @@ 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 DESIGN_TOKENS = {
   "color-no-hex": true,
   "color-named": "never",
@@ -87,17 +131,24 @@ 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 {