@avi2dg/checks 0.44.0 → 0.45.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.45.1
+
+Released 2026-10-19.
+
+### Fixes
+
+- **quality:** pass @property in the Baseline CSS gate at every target [#169](https://github.com/avi2d/checks/pull/169)
+
+## 0.45.0
+
+Released 2026-10-18.
+
+### Breaking changes
+
+- **quality:** hold CSS to the stylelint rule families set in stylelint.config.ts [#167](https://github.com/avi2d/checks/pull/167)
+
 ## 0.44.0
 
 Released 2026-10-18.

package/README.md

@@ -1,7 +1,7 @@
 # checks
 
 `@avi2dg/checks` is the kit of deterministic checks a TypeScript repository installs to hold its code, tests, commits, CI wiring and docs to one shared standard.
-It ships the lint gates `checks-lint` runs over each pull request, the test runners, and a `defineConfig` for oxlint, Knip and dependency-cruiser.
+It ships the lint gates `checks-lint` runs over each pull request, the test runners, and a `defineConfig` for oxlint, Knip, dependency-cruiser and stylelint.
 It also ships the configs a repository extends for tsc, commitlint, bun and Stryker.
 Each repository owns its workflows and native tool configs, as [Native settings](docs/configs/native-settings.md) maps.
 
@@ -26,6 +26,8 @@ Each repository owns its workflows and native tool configs, as [Native settings]
   - `playwright-core` 1.63.0
   - `postcss-html` 2.0.0
   - `stylelint` 17.16.0
+  - `stylelint-config-standard` 40.0.0
+  - `stylelint-plugin-use-baseline` 1.4.7
 
 <!-- end generated prerequisites -->
 
@@ -234,7 +236,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `dependency-cruiser.config.js` | the kit's dependency-cruiser rules as a base a `.dependency-cruiser.cjs` extends by path, which the build writes |
 | `knip-base.json` | the Knip `include` setting, for a configuration that spreads it |
 | `src/` | every bin, which a package script calls by its `checks-` name, the modules the bins import, and the Effect language service severities under `src/quality/presets/` |
-| `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip` and `@avi2dg/checks/dependency-cruiser` resolve to, and the doc templates, one template per kind of doc file |
+| `dist/` | the compiled oxlint plugins, the config builders `@avi2dg/checks/oxlint`, `@avi2dg/checks/knip`, `@avi2dg/checks/dependency-cruiser` and `@avi2dg/checks/stylelint` resolve to, and the doc templates, one template per kind of doc file |
 | `oxlintrc.json` | the oxlint `base` as a config a `.oxlintrc.json` extends by path, which the build writes |
 | `stryker.preset.js` | the Stryker mutation-testing preset, which refuses a full run outside CI |
 | `tsconfig.effect.json` | the tsconfig fragment with the shared compiler options and the Effect language-service block |

package/dist/presets/stylelint.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from "stylelint";
+type Globs = readonly [string, ...string[]];
+export type BaselineTarget = "widely" | "newly" | number;
+export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
+    readonly baseline: BaselineTarget;
+    readonly tokens: Globs | false;
+};
+export declare const MARKUP: readonly ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
+export declare function defineConfig({ baseline, tokens, rules, overrides, ...rest }: ChecksStylelintConfig): Config;
+export {};

package/dist/presets/stylelint.js

@@ -0,0 +1,84 @@
+// src/quality/presets/stylelint.ts
+import { fileURLToPath } from "node:url";
+var HTML_AND_ASTRO = ["**/*.html", "**/*.astro"];
+var MARKUP = [...HTML_AND_ASTRO, "**/*.vue", "**/*.svelte"];
+function peer(name) {
+  return fileURLToPath(import.meta.resolve(name));
+}
+var CONVENTION_CHANGES = {
+  "no-descending-specificity": null,
+  "property-no-vendor-prefix": [true, { disableFix: true, ignoreProperties: ["-webkit-user-select"] }]
+};
+var SELECTOR_COMPLEXITY = {
+  "selector-max-specificity": "0,3,2",
+  "selector-max-compound-selectors": 3
+};
+var COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"];
+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"] }
+};
+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";
+function baselineTarget(baseline) {
+  if (baseline === "widely" || baseline === "newly")
+    return baseline;
+  if (typeof baseline === "number" && Number.isInteger(baseline))
+    return baseline;
+  throw new TypeError(REFUSED_BASELINE);
+}
+function isGlobList(value) {
+  return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");
+}
+function tokenFiles(tokens) {
+  if (tokens === false)
+    return [];
+  if (isGlobList(tokens) && tokens.length > 0)
+    return tokens;
+  throw new TypeError(REFUSED_TOKENS);
+}
+var BASELINE_RULE = "plugin/use-baseline";
+function passProperty(entry) {
+  if (entry === null || entry === undefined)
+    return entry;
+  const [primary, options = {}] = Array.isArray(entry) ? entry : [entry];
+  const ignored = Reflect.get(options, "ignoreAtRules") ?? [];
+  if (!Array.isArray(ignored))
+    return entry;
+  return [primary, { ...options, ignoreAtRules: ["property", ...ignored] }];
+}
+function designTokens(files) {
+  if (files.length === 0)
+    return { rules: {}, overrides: [] };
+  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 }) {
+  const available = baselineTarget(baseline);
+  const tokenRules = designTokens(tokenFiles(tokens));
+  const merged = {
+    ...CONVENTION_CHANGES,
+    ...SELECTOR_COMPLEXITY,
+    [BASELINE_RULE]: [true, { available }],
+    ...tokenRules.rules,
+    ...rules
+  };
+  return {
+    ...rest,
+    extends: [peer("stylelint-config-standard")],
+    plugins: [peer("stylelint-plugin-use-baseline")],
+    rules: { ...merged, [BASELINE_RULE]: passProperty(merged[BASELINE_RULE]) },
+    overrides: [
+      { files: [...MARKUP], customSyntax: peer("postcss-html") },
+      { files: [...HTML_AND_ASTRO], rules: { "declaration-block-single-line-max-declarations": null } },
+      ...tokenRules.overrides,
+      ...overrides
+    ]
+  };
+}
+export {
+  MARKUP,
+  defineConfig
+};

package/docs/configs/native-settings.md

@@ -13,9 +13,11 @@ A consuming repository puts each setting in the file its tool reads, and no mani
 | `.github/workflows/*.yml` | Pull request commands, scheduled commands, runner labels | GitHub Actions and `checks-ci-wiring` |
 | `oxlint.config.ts` | Effect paths and their exemptions, ignore patterns, and any rule or budget the repository sets over the kit's defaults | oxlint and `checks-effect-scope` |
 | `oxlint-suppressions.json` | The existing violations oxlint suppresses, per file and rule | oxlint and `checks-suppressions-ratchet` |
+| `stylelint-suppressions.json` | The existing violations stylelint suppresses, per file and rule | stylelint, `checks-frontend-syntax` and `checks-suppressions-ratchet` |
 | `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` |
 | `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` |
@@ -29,7 +31,7 @@ A page whose front matter sets `audience: consumers` names commands that a consu
 
 ## The config builders
 
-The kit ships a `defineConfig` for oxlint, Knip and dependency-cruiser.
+The kit ships a `defineConfig` for oxlint, Knip, dependency-cruiser and stylelint.
 Each takes the tool's own config type, less the keys the kit owns, and returns the whole config with a default for every kit rule.
 A key only the repository knows has no default, so `tsc` refuses a config that leaves it out.
 The builder throws when the tool loads such a config anyway.
@@ -39,6 +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` |
 
 A repository whose sources are Effect programs writes `oxlint.config.ts`:
 
@@ -75,7 +78,16 @@ export default defineConfig({ devOnly: ["^(?:evals|tests)/"] });
 ```
 
 [The dependency rules](dependency-rules.md) lists its keys.
-`tsconfig.json` keeps the three config files in its program, so `bun run typecheck` holds them to the builders' types.
+
+A repository that declares `frontend-syntax.json` writes `stylelint.config.ts`, which [checks-frontend-syntax](../gates/checks-frontend-syntax.md) loads and describes:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/stylelint";
+
+export default defineConfig({ baseline: "widely", tokens: false });
+```
+
+`tsconfig.json` keeps the config files in its program, so `bun run typecheck` holds them to the builders' types.
 
 ## Size limits
 
@@ -108,4 +120,5 @@ overrides: [{ files: ["src/lib/server.ts"], rules: { "max-lines": ["error", { ma
 - [The dependency rules](dependency-rules.md)
 - [checks-ci-wiring](../gates/checks-ci-wiring.md)
 - [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md)
+- [checks-frontend-syntax](../gates/checks-frontend-syntax.md)
 - [checks-docs](../gates/checks-docs.md)

package/docs/design.md

@@ -302,7 +302,12 @@ So a product opts in by declaring `browser-checks.json`, `checks-lint` never sta
 `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 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.
+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.
 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.
 

package/docs/gates/checks-comment-gate.md

@@ -10,6 +10,8 @@ audience: consumers
 
 It fails when an added line carries a banned comment.
 It refuses a machine-read directive, a record or ticket pointer, a doc block, and a file opening with a rationale block over three lines, licence headers excepted.
+The directives are `@ts-expect-error`, `@ts-ignore`, `biome-ignore`, `prettier-ignore`, and every directive that begins `eslint-disable` or `stylelint-disable`, such as `stylelint-disable-next-line`.
+A stylesheet keeps its count of existing stylelint problems in `stylelint-suppressions.json` instead, as [checks-frontend-syntax](checks-frontend-syntax.md) says.
 Each refusal says what to write instead.
 Only added lines are checked, so a violation in a file the diff never touches stays silent.
 A refusal counts when any line of the comment carrying it was added.

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

@@ -4,11 +4,18 @@ 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`.
+`checks-frontend-syntax` is the opt-in gate that holds a repository's CSS to stylelint, under the kit's two rules of its own and the rule families of `@avi2dg/checks/stylelint`.
 
 ## What it checks
 
-It runs stylelint with two of stylelint's own rules, and with no other rule and no repository config:
+It runs stylelint twice over each declared input.
+The repository run holds the families the repository's `stylelint.config.ts` sets, and applies `--fix`.
+The kit run then holds the kit's two rules over each file the repository run matched.
+It reads no repository config and no count in `stylelint-suppressions.json`, so neither turns those rules off.
+
+### The kit's two rules
+
+The kit run refuses two CSS constraints a program can decide, a transition over `all` and a body-wide `user-select`:
 
 | Rule | What it refuses | Why |
 | --- | --- | --- |
@@ -19,7 +26,37 @@ The second rule refuses any value on those selectors, so `body { user-select: te
 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.
+A control that needs selection off sets it on its own selector, such as `.drag-handle { user-select: none; }`, which this rule passes and the Baseline family reports.
+
+### The rule families
+
+`defineConfig` from `@avi2dg/checks/stylelint` builds the config the repository run holds:
+
+| Family | Rules | Default |
+| --- | --- | --- |
+| 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 |
+| 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 |
+
+The builder changes three 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.
+- In an `.html` or `.astro` file, `declaration-block-single-line-max-declarations` is off, since a `style` attribute is one line.
+
+CSS repetition is not a family of this gate: a repository adds `"css"` to `format` in `.jscpd.json`, and [checks-repetition](checks-repetition.md) then fails when a stylesheet's repeated lines grow.
+
+### What no comment turns off
+
+It sets stylelint's `ignoreDisables`, so a `stylelint-disable` comment silences nothing in either run, and [checks-comment-gate](checks-comment-gate.md) refuses one on the line that adds it.
+A repository adopts a family over existing problems by counting them in `stylelint-suppressions.json` with `--suppress`.
+stylelint lets a file and rule through while its problems stay within the count, and [checks-suppressions-ratchet](checks-suppressions-ratchet.md) fails a change that raises a count.
+`--suppress` counts only what the repository run reports, and a file that does not parse still fails in the kit run.
+
+### Files
 
 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.
@@ -28,7 +65,7 @@ It fails on each declared input that matches no file, so an input that a renamed
 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.
+- 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.
 - `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.
@@ -49,35 +86,71 @@ A glob over built output, such as `dist/**/*.html`, judges the styles a framewor
 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:
+It imports `stylelint.config.ts` from the same directory, and passes its default export to stylelint:
+
+```ts
+import { defineConfig } from "@avi2dg/checks/stylelint";
+
+export default defineConfig({
+  baseline: "widely",
+  tokens: ["src/styles/tokens.css"],
+});
+```
+
+`baseline` and `tokens` have no default, since only the repository knows them, so `tsc` refuses a config that leaves either out.
+The builder throws when the gate loads such a config anyway.
+
+| Key | Takes |
+| --- | --- |
+| `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` |
+
+`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:
+
+```ts
+rules: { "plugin/use-baseline": [true, { available: "widely", ignoreProperties: { "user-select": ["none"] } }] },
+```
+
+`@property` needs no such exception, since the kit passes it at every target, and adds it to the `ignoreAtRules` of a `plugin/use-baseline` entry the repository sets.
+
+The builder owns `extends` and `plugins`.
+It resolves the shared config, the plugin and `postcss-html` beside the kit, so they need not sit under the directory the gate runs in.
+stylelint cannot load `stylelint.config.ts` itself under TypeScript 7, so a bare `stylelint --fix` finds no config, and the gate's `--fix` stands in for it.
+A config not built with `defineConfig` names its own `customSyntax` for markup, or each `.html` or `.astro` file fails to parse in the repository run.
+
+The repository installs the optional peers the gate loads, at the versions the kit pins:
 
 ```sh
-bun add -d stylelint@17.16.0 postcss-html@2.0.0
+bun add -d stylelint@17.16.0 postcss-html@2.0.0 stylelint-config-standard@40.0.0 stylelint-plugin-use-baseline@1.4.7
 ```
 
 ## Arguments
 
 ```sh
-checks-frontend-syntax [<directory>]
+checks-frontend-syntax [--fix] [--suppress] [<directory>]
 ```
 
 It checks the directory it runs in, or the directory it is given.
+`--fix` rewrites what a rule of the config fixes, such as `#ffffff` to `#fff`, and reports what is left.
+`--suppress` writes each problem the config reports into `stylelint-suppressions.json`, and drops a count whose problems are gone.
 
 ## 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 |
+| 0 | every declared input matches a file, and no file holds a problem beyond its suppressed count |
+| 1 | a file holds a problem 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, `stylelint.config.ts` is missing or does not load, stylelint refuses an option, a peer cannot load, or an argument is unknown |
 
 ## Sample output
 
 ```
-frontend-syntax: 3 problem(s) in 2 file(s) from 3 declared input(s):
+frontend-syntax: 4 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.
+  src/styles/site.css:9:1 Too high specificity in ".nav .item.is-open > a:hover", maximum "0,3,2" (selector-max-specificity)
 ```
 
 A passing run counts what it judged:
@@ -89,9 +162,13 @@ 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`.
+A repository without that file never runs it and needs neither `stylelint.config.ts` nor the peers.
 
 ## Related topics
 
 - [checks-browser](checks-browser.md)
 - [checks-lint](checks-lint.md)
+- [checks-comment-gate](checks-comment-gate.md)
+- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)
+- [checks-repetition](checks-repetition.md)
+- [Native settings](../configs/native-settings.md)

package/docs/gates/checks-repetition.md

@@ -23,6 +23,8 @@ A `path` entry the base revision lacks reads as empty there, so a newly measured
 { "path": ["src"], "format": ["typescript"], "ignore": ["**/*.d.ts"] }
 ```
 
+A repository that lists `"css"` in `format` measures its stylesheets the same way, and [checks-frontend-syntax](checks-frontend-syntax.md) leaves CSS repetition to this gate.
+
 The gate sets the 50 tokens and 5 lines itself, over any the file names.
 A `threshold` the file names never fails the gate, which reads jscpd's report once the scan finishes.
 The bin reads the base and head commits rather than the working tree's file contents.
@@ -56,5 +58,6 @@ When the head holds no `.jscpd.json`, the gate reports that no file was measured
 
 ## Related topics
 
+- [checks-frontend-syntax](checks-frontend-syntax.md)
 - [Native settings](../configs/native-settings.md)
 - [checks-suppressions-ratchet](checks-suppressions-ratchet.md)

package/docs/gates/checks-suppressions-ratchet.md

@@ -4,18 +4,19 @@ audience: consumers
 ---
 # checks-suppressions-ratchet
 
-`checks-suppressions-ratchet` is the gate that fails when a change raises a count in `oxlint-suppressions.json`.
+`checks-suppressions-ratchet` is the gate that fails when a change raises a count in `oxlint-suppressions.json` or `stylelint-suppressions.json`.
 
 ## What it checks
 
 oxlint accepts whatever `oxlint --suppress-all` writes to `oxlint-suppressions.json`, so raising a count to let a new site through passes the lint.
-The ratchet fails naming each file and rule whose count rose or that appeared.
+stylelint accepts `stylelint-suppressions.json` the same way, and writes it in the same shape, a count per rule per file.
+The ratchet fails naming the suppressions file, the file and the rule of each count that rose or appeared.
 A count that fell and an entry that went both pass.
 
 ## What it reads
 
-It reads `oxlint-suppressions.json` at a base and at a head, from the directory the command runs in, which is where oxlint writes it.
-A commit without the file counts as empty, so the commit that first adds a baseline fails with every entry appearing.
+It reads `oxlint-suppressions.json` and `stylelint-suppressions.json` at a base and at a head, from the directory the command runs in, which is where oxlint and stylelint write them.
+A commit without a file counts it as empty, so the commit that first adds a baseline fails with every entry appearing.
 
 ## Arguments
 
@@ -33,22 +34,23 @@ With one it compares that commit with its parent, or with the empty tree for a r
 | --- | --- |
 | 0 | no count rose and no entry appeared |
 | 1 | a count rose or an entry appeared |
-| 2 | a ref does not resolve, the parent exists but is not in the clone, or the file is not oxlint's count per rule per file |
+| 2 | a ref does not resolve, the parent exists but is not in the clone, or a file is not a count per rule per file |
 
 ## Sample output
 
 ```
-suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; fix the site instead of suppressing it:
-  src/added.ts typescript/no-unsafe-type-assertion appeared with 1
-  src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
+suppressions-ratchet: 2 count(s) rose or appeared; fix the site instead of suppressing it:
+  oxlint-suppressions.json src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
+  stylelint-suppressions.json src/styles.css selector-max-specificity appeared with 1
 ```
 
 ## When it runs
 
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
-A repository with no `oxlint-suppressions.json` passes, since both ends count as empty.
+A repository with neither file passes, since both ends count as empty.
 
 ## Related topics
 
 - [The Effect rules](../configs/effect-rules.md)
+- [checks-frontend-syntax](checks-frontend-syntax.md)
 - [checks-lint](checks-lint.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.44.0",
+  "version": "0.45.1",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -94,6 +94,7 @@
     "src/quality/presets/effect.language-service.json",
     "src/quality/presets/oxlint.ts",
     "src/quality/presets/dependency-cruiser.ts",
+    "src/quality/presets/stylelint.ts",
     "src/quality/effect-scope.ts",
     "src/quality/jsonc-patch.ts",
     "src/dependencies/imports.ts",
@@ -129,6 +130,10 @@
     "./dependency-cruiser": {
       "types": "./dist/presets/dependency-cruiser.d.ts",
       "default": "./dist/presets/dependency-cruiser.js"
+    },
+    "./stylelint": {
+      "types": "./dist/presets/stylelint.d.ts",
+      "default": "./dist/presets/stylelint.js"
     }
   },
   "bin": {
@@ -170,7 +175,7 @@
   },
   "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 --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 && 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",
@@ -192,6 +197,8 @@
     "playwright-core": "1.63.0",
     "postcss-html": "2.0.0",
     "stylelint": "17.16.0",
+    "stylelint-config-standard": "40.0.0",
+    "stylelint-plugin-use-baseline": "1.4.7",
     "typescript": "7.0.2"
   },
   "peerDependenciesMeta": {
@@ -209,6 +216,12 @@
     },
     "stylelint": {
       "optional": true
+    },
+    "stylelint-config-standard": {
+      "optional": true
+    },
+    "stylelint-plugin-use-baseline": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -229,6 +242,8 @@
     "playwright-core": "1.63.0",
     "postcss-html": "2.0.0",
     "stylelint": "17.16.0",
+    "stylelint-config-standard": "40.0.0",
+    "stylelint-plugin-use-baseline": "1.4.7",
     "typescript": "7.0.2"
   },
   "dependencies": {

package/src/complexity/suppressions-ratchet.ts

@@ -3,13 +3,15 @@ import { Console, Effect, Schema } from "effect";
 import { git, commitOf, parentOrEmptyTree, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 
-export const SUPPRESSIONS = "oxlint-suppressions.json";
+export const SUPPRESSIONS = ["oxlint-suppressions.json", "stylelint-suppressions.json"] as const;
+
+export type SuppressionsFile = (typeof SUPPRESSIONS)[number];
 
 export type Suppressions = ReadonlyMap<string, ReadonlyMap<string, number>>;
 
-export type Rise =
-  | { readonly kind: "rose"; readonly file: string; readonly rule: string; readonly base: number; readonly head: number }
-  | { readonly kind: "appeared"; readonly file: string; readonly rule: string; readonly head: number };
+type Place = { readonly list: SuppressionsFile; readonly file: string; readonly rule: string };
+
+export type Rise = Place & ({ readonly kind: "rose"; readonly base: number; readonly head: number } | { readonly kind: "appeared"; readonly head: number });
 
 export type Ratchet = {
   readonly counted: number;
@@ -49,40 +51,44 @@ export const parseSuppressions = Effect.fn("parseSuppressions")(function* (
   return suppressions;
 });
 
-type Count = {
-  readonly file: string;
-  readonly rule: string;
-  readonly count: number;
-};
+type Count = Place & { readonly count: number };
 
-function countsOf(suppressions: Suppressions): readonly Count[] {
-  return [...suppressions].flatMap(([file, rules]) => [...rules].map(([rule, count]) => ({ file, rule, count })));
+function countsOf(list: SuppressionsFile, suppressions: Suppressions): readonly Count[] {
+  return [...suppressions].flatMap(([file, rules]) => [...rules].map(([rule, count]) => ({ list, file, rule, count })));
 }
 
-function riseOf({ file, rule, count }: Count, before: number | undefined): readonly Rise[] {
-  if (before === undefined) return count > 0 ? [{ kind: "appeared", file, rule, head: count }] : [];
-  return count > before ? [{ kind: "rose", file, rule, base: before, head: count }] : [];
+function riseOf({ count, ...place }: Count, before: number | undefined): readonly Rise[] {
+  if (before === undefined) return count > 0 ? [{ ...place, kind: "appeared", head: count }] : [];
+  return count > before ? [{ ...place, kind: "rose", base: before, head: count }] : [];
 }
 
-export function compareSuppressions(base: Suppressions, head: Suppressions): Ratchet {
-  const counts = countsOf(head);
+export function compareSuppressions(list: SuppressionsFile, base: Suppressions, head: Suppressions): Ratchet {
+  const counts = countsOf(list, head);
   const rises = counts.flatMap((counted) => riseOf(counted, base.get(counted.file)?.get(counted.rule)));
-  const lowered = countsOf(base).filter(({ file, rule, count }) => (head.get(file)?.get(rule) ?? 0) < count).length;
+  const lowered = countsOf(list, base).filter(({ file, rule, count }) => (head.get(file)?.get(rule) ?? 0) < count).length;
   rises.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
   return { counted: counts.length, lowered, rises };
 }
 
+export function combined(ratchets: readonly Ratchet[]): Ratchet {
+  return {
+    counted: ratchets.reduce((sum, { counted }) => sum + counted, 0),
+    lowered: ratchets.reduce((sum, { lowered }) => sum + lowered, 0),
+    rises: ratchets.flatMap(({ rises }) => rises),
+  };
+}
+
 function describeRise(rise: Rise): string {
   const change = rise.kind === "rose" ? `rose from ${rise.base} to ${rise.head}` : `appeared with ${rise.head}`;
-  return `${rise.file} ${rise.rule} ${change}`;
+  return `${rise.list} ${rise.file} ${rise.rule} ${change}`;
 }
 
 export function report({ counted, lowered, rises }: Ratchet): string {
   if (rises.length === 0) {
-    return `suppressions-ratchet: no count in ${SUPPRESSIONS} rose or appeared (${counted} at the head, ${lowered} lowered)`;
+    return `suppressions-ratchet: no count in ${SUPPRESSIONS.join(" or ")} rose or appeared (${counted} at the head, ${lowered} lowered)`;
   }
   return [
-    `suppressions-ratchet: ${rises.length} count(s) in ${SUPPRESSIONS} rose or appeared; fix the site instead of suppressing it:`,
+    `suppressions-ratchet: ${rises.length} count(s) rose or appeared; fix the site instead of suppressing it:`,
     ...rises.map((rise) => `  ${describeRise(rise)}`),
   ].join("\n");
 }
@@ -94,22 +100,28 @@ const mergeBase = Effect.fn("mergeBase")(function* (base: string, head: string)
   return commit.trim();
 });
 
-const suppressionsAt = Effect.fn("suppressionsAt")(function* (treeish: string) {
-  const blob = (yield* git(["ls-tree", "--object-only", treeish, "--", SUPPRESSIONS])).trim();
+const suppressionsAt = Effect.fn("suppressionsAt")(function* (list: SuppressionsFile, treeish: string) {
+  const blob = (yield* git(["ls-tree", "--object-only", treeish, "--", list])).trim();
   if (blob === "") return new Map() satisfies Suppressions;
-  return yield* parseSuppressions(yield* git(["cat-file", "blob", blob]), `${SUPPRESSIONS} at ${treeish}`);
+  return yield* parseSuppressions(yield* git(["cat-file", "blob", blob]), `${list} at ${treeish}`);
+});
+
+const compareAt = Effect.fn("compareAt")(function* (base: string, head: string) {
+  const ratchets: Ratchet[] = [];
+  for (const list of SUPPRESSIONS) ratchets.push(compareSuppressions(list, yield* suppressionsAt(list, base), yield* suppressionsAt(list, head)));
+  return combined(ratchets);
 });
 
 export const runRange = Effect.fn("runRange")(function* (base: string, head: string) {
   const headCommit = yield* commitOf(head);
   // At the base tip, a count the base branch lowered after the head branched off would read as a rise at the head.
   const branchPoint = yield* mergeBase(yield* commitOf(base), headCommit);
-  return compareSuppressions(yield* suppressionsAt(branchPoint), yield* suppressionsAt(headCommit));
+  return yield* compareAt(branchPoint, headCommit);
 });
 
 export const runTip = Effect.fn("runTip")(function* (tip: string) {
   const tipCommit = yield* commitOf(tip);
-  return compareSuppressions(yield* suppressionsAt(yield* parentOrEmptyTree(tipCommit)), yield* suppressionsAt(tipCommit));
+  return yield* compareAt(yield* parentOrEmptyTree(tipCommit), tipCommit);
 });
 
 const ratchet = Effect.gen(function* () {

package/src/core/declared-inputs.ts

@@ -56,12 +56,13 @@ export function inputsReport(name: string, inputs: readonly Input[], problems: r
   return [`${name}: ${problems.length} problem(s) in ${scanned}:`, ...problems.map((problem) => `  ${problem}`)].join("\n");
 }
 
-const declaredGate = Effect.fn("declaredGate")(function* <S, E>(
+export const declaredGate = Effect.fn("declaredGate")(function* <S, E>(
   declared: Declared,
   scanInputs: (root: string, globs: readonly string[]) => Effect.Effect<S, E, BunServices.BunServices>,
   { report, passes }: Verdict<S>,
+  directory: string | undefined,
 ) {
-  const root = (yield* Path.Path).resolve(process.argv[2] ?? ".");
+  const root = (yield* Path.Path).resolve(directory ?? ".");
   const scan = yield* scanInputs(root, yield* readInputs(root, declared));
   yield* Console.log(report(scan));
   return passes(scan);
@@ -72,5 +73,5 @@ export function runDeclaredGate<S, E extends { readonly message: string }>(
   scanInputs: (root: string, globs: readonly string[]) => Effect.Effect<S, E, BunServices.BunServices>,
   verdict: Verdict<S>,
 ): void {
-  runMain(declared.name, declaredGate(declared, scanInputs, verdict));
+  runMain(declared.name, declaredGate(declared, scanInputs, verdict, process.argv[2]));
 }

package/src/quality/comment-matchers.ts

@@ -40,6 +40,7 @@ const SQL: Syntax = { line: DASHES, block: SLASHES, quotes: STRINGS, regexLitera
 const LUA: Syntax = { line: DASHES, block: [["--[[", "]]"]], quotes: STRINGS, regexLiterals: false };
 const HASKELL: Syntax = { line: DASHES, block: [["{-", "-}"]], quotes: [escaping('"')], regexLiterals: false };
 const ML: Syntax = { line: [], block: [["(*", "*)"]], quotes: [escaping('"')], regexLiterals: false };
+const CSS: Syntax = { line: [], block: SLASHES, quotes: STRINGS, regexLiterals: false };
 
 export const SYNTAXES: Readonly<Record<string, Syntax>> = {
   ts: JS,
@@ -78,6 +79,7 @@ export const SYNTAXES: Readonly<Record<string, Syntax>> = {
   yml: YAML,
   toml: HASH,
   ml: ML,
+  css: CSS,
 };
 
 const extensionOf = (path: string): string => path.slice(path.lastIndexOf(".") + 1);
@@ -247,13 +249,14 @@ export const REFUSED_DIRECTIVES = [
   "biome-ignore",
   "eslint-disable",
   "prettier-ignore",
+  "stylelint-disable",
 ] as const satisfies readonly string[];
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 const directiveSource = (name: string): string => {
   const escaped = escapeRegExp(name);
-  if (name === "eslint-disable") return `\\b${escaped}[\\w-]*`;
+  if (name.endsWith("-disable")) return `\\b${escaped}[\\w-]*`;
   return /^[\w]/.test(name) ? `\\b${escaped}\\b` : escaped;
 };
 

package/src/quality/frontend-syntax.ts

@@ -1,33 +1,47 @@
 #!/usr/bin/env bun
-import { Effect, Path, Schema } from "effect";
-import type { LintResult } from "stylelint";
-import { emptyInputs, inputsReport, runDeclaredGate, violationLine, type Declared, type Input, type Violation } from "../core/declared-inputs.ts";
-import { Usage } from "../core/main.ts";
+import { Effect, FileSystem, Path, Schema } from "effect";
+import type { Config, LinterOptions, LintResult } from "stylelint";
+import { declaredGate, emptyInputs, inputsReport, violationLine, type Declared, type Input, type Violation } from "../core/declared-inputs.ts";
+import { runMain, Usage } from "../core/main.ts";
+import { MARKUP } from "./presets/stylelint.ts";
 
 const DECLARED: Declared = { name: "frontend-syntax", file: "frontend-syntax.json", declares: "inputs" };
 
+const STYLELINT_CONFIG = "stylelint.config.ts";
+
+const USAGE = "usage: frontend-syntax.ts [--fix] [--suppress] [<directory>]";
+
 const TRANSITION_ALL = "declaration-property-value-disallowed-list";
 const BODY_WIDE_USER_SELECT = "rule-selector-property-disallowed-list";
 const UNPARSED = "CssSyntaxError";
+const UNPARSED_PART = "parseError";
 
 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>> = {
+type Advice = Readonly<Record<string, string>>;
+
+const JUDGES_ONLY_WHAT_PARSES = "The gate judges only what parses.";
+
+const UNPARSED_ADVICE: Advice = { [UNPARSED]: JUDGES_ONLY_WHAT_PARSES, [UNPARSED_PART]: JUDGES_ONLY_WHAT_PARSES };
+
+const KIT_ADVICE: Advice = {
   [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.",
+  ...UNPARSED_ADVICE,
 };
 
-const MARKUP = ["**/*.html", "**/*.astro", "**/*.vue", "**/*.svelte"];
-
 export type Scan = {
   readonly inputs: readonly Input[];
   readonly violations: readonly Violation[];
 };
 
+type Options = { readonly fix: boolean; readonly suppress: boolean };
+
+type Pass = { readonly config: Config; readonly advice: Advice; readonly refuses: string };
+
 class FrontendSyntaxError extends Schema.TaggedError<FrontendSyntaxError>()("FrontendSyntaxError", {
   message: Schema.String,
 }) {}
@@ -45,41 +59,98 @@ const loadPeer = <A>(name: string, load: () => Promise<A>) =>
       new Usage({ message: `cannot load ${name}, which a repository that declares ${DECLARED.file} installs beside the kit as an optional peer` }),
   });
 
-function violationsOf(result: LintResult, relative: (file: string) => string): readonly Violation[] {
+const ConfigModule = Schema.Struct({ default: Schema.Record(Schema.String, Schema.Unknown) });
+
+const decodeConfigModule = Schema.decodeUnknownEffect(ConfigModule);
+
+const loadRepositoryConfig = Effect.fn("loadRepositoryConfig")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const file = (yield* Path.Path).join(root, STYLELINT_CONFIG);
+  if (!(yield* fs.exists(file))) {
+    return yield* new Usage({
+      message: `${STYLELINT_CONFIG} is missing, and a repository that declares ${DECLARED.file} writes it with defineConfig from @avi2dg/checks/stylelint`,
+    });
+  }
+  const loaded: unknown = yield* Effect.tryPromise({
+    try: () => import(file),
+    catch: (cause) => new Usage({ message: `${STYLELINT_CONFIG} does not load: ${String(cause)}` }),
+  });
+  const module = yield* decodeConfigModule(loaded).pipe(
+    Effect.mapError(() => new Usage({ message: `${STYLELINT_CONFIG} has no default export of a stylelint config object` })),
+  );
+  return module.default;
+});
+
+function violationsOf(result: LintResult, relative: (file: string) => string, advice: Advice): 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(),
-  }));
+  const unparsed = result.parseErrors.map(({ line, column, stylelintType, text }) => ({ line, column, rule: stylelintType, text }));
+  return [...result.warnings, ...unparsed].map(({ line, column, rule, text }) => {
+    const advised = advice[rule];
+    return { file, line, column, text: advised === undefined ? text : `${text.replace(` (${rule})`, "")}. ${advised}` };
+  });
 }
 
-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 lintWith = (root: string, pass: Pass, options: Partial<LinterOptions>) =>
+  Effect.gen(function* () {
+    const stylelint = (yield* loadPeer("stylelint", () => import("stylelint"))).default;
+    const files = options.files ?? [];
     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)}` })),
+      try: () => stylelint.lint({ ...options, cwd: root, configBasedir: root, config: pass.config, ignoreDisables: true }),
+      catch: (cause) => (isNoFilesFound(cause) ? new NoFilesFound() : new FrontendSyntaxError({ message: `stylelint fails on ${String(files)}: ${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 invalid = linted.flatMap(({ invalidOptionWarnings }) => invalidOptionWarnings.map(({ text }) => text));
+    if (invalid.length > 0) return yield* new FrontendSyntaxError({ message: `stylelint refuses ${pass.refuses}: ${[...new Set(invalid)].join("; ")}` });
+    return linted;
+  });
+
+// stylelint applies stylelint-suppressions.json to every file it reads itself, and to no code it is handed.
+const lintUnsuppressed = (root: string, pass: Pass, files: readonly string[]) =>
+  Effect.forEach(files, (file) =>
+    Effect.gen(function* () {
+      const code = yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+        Effect.mapError((cause) => new FrontendSyntaxError({ message: `cannot read ${file}: ${String(cause)}` })),
+      );
+      return yield* lintWith(root, pass, { code, codeFilename: file });
+    }),
+  ).pipe(Effect.map((results) => results.flat()));
+
+function isJudged({ ignored }: LintResult): boolean {
+  return ignored !== true;
+}
+
+const passesFor = Effect.fn("passesFor")(function* (root: string) {
+  const html = (yield* loadPeer("postcss-html", () => import("postcss-html"))).default;
+  const kit: Pass = { config: { rules: RULES, overrides: [{ files: [...MARKUP], customSyntax: html }] }, advice: KIT_ADVICE, refuses: "the kit's rule options" };
+  const repository: Pass = {
+    config: { ...(yield* loadRepositoryConfig(root)), quiet: false },
+    advice: UNPARSED_ADVICE,
+    refuses: `an option in ${STYLELINT_CONFIG}`,
+  };
+  return { kit, repository };
+});
+
+export const scanInputs = Effect.fn("scanInputs")(function* (root: string, globs: readonly string[], { fix, suppress }: Options) {
+  const path = yield* Path.Path;
+  // stylelint keys its suppressions file on the process directory rather than on its cwd option.
+  yield* Effect.sync(() => process.chdir(root));
+  const { kit, repository } = yield* passesFor(root);
+  if (suppress) yield* lintWith(root, repository, { files: [...globs], fix, suppressAll: true, allowEmptyInput: true });
+  const relative = (file: string): string => path.relative(root, file);
+  const inputs: Input[] = [];
+  const violations = new Map<string, Violation>();
+  for (const glob of globs) {
+    const matched = yield* lintWith(root, repository, { files: glob, fix });
+    const judged = matched.filter(isJudged);
+    const ruled = yield* lintUnsuppressed(root, kit, matched.flatMap(({ source }) => (source === undefined ? [] : [source])));
+    const files = new Set([...judged, ...ruled.filter(isJudged)].map((result) => relative(result.source ?? "")));
+    inputs.push({ glob, files: [...files].toSorted() });
+    const found = [...ruled.flatMap((result) => violationsOf(result, relative, kit.advice)), ...judged.flatMap((result) => violationsOf(result, relative, repository.advice))];
+    for (const violation of found) 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;
+  const byPlace = (a: Violation, b: Violation): number => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.text.localeCompare(b.text);
   return { inputs, violations: [...violations.values()].toSorted(byPlace) } satisfies Scan;
 });
 
@@ -92,4 +163,19 @@ export function report({ inputs, violations }: Scan): string {
   return inputsReport(DECLARED.name, inputs, [...empty, ...violations.map(violationLine)]);
 }
 
-if (import.meta.main) runDeclaredGate(DECLARED, scanInputs, { report, passes });
+type Arguments = Options & { readonly directory: string | undefined };
+
+export const parseArguments = Effect.fn("parseArguments")(function* (args: readonly string[]) {
+  const flags = new Set(args.filter((arg) => arg.startsWith("--")));
+  const directories = args.filter((arg) => !arg.startsWith("--"));
+  const unknown = [...flags].filter((flag) => flag !== "--fix" && flag !== "--suppress");
+  if (unknown.length > 0 || directories.length > 1) return yield* new Usage({ message: USAGE });
+  return { fix: flags.has("--fix"), suppress: flags.has("--suppress"), directory: directories[0] } satisfies Arguments;
+});
+
+const gate = Effect.gen(function* () {
+  const { directory, ...options } = yield* parseArguments(process.argv.slice(2));
+  return yield* declaredGate(DECLARED, (root, globs) => scanInputs(root, globs, options), { report, passes }, directory);
+});
+
+if (import.meta.main) runMain(DECLARED.name, gate);

package/src/quality/presets/stylelint.ts

@@ -0,0 +1,103 @@
+import { fileURLToPath } from "node:url";
+import type { Config } from "stylelint";
+
+type Globs = readonly [string, ...string[]];
+
+export type BaselineTarget = "widely" | "newly" | number;
+
+export type ChecksStylelintConfig = Omit<Config, "extends" | "plugins"> & {
+  readonly baseline: BaselineTarget;
+  readonly tokens: Globs | false;
+};
+
+type Rules = NonNullable<Config["rules"]>;
+
+const HTML_AND_ASTRO = ["**/*.html", "**/*.astro"] as const;
+
+export const MARKUP = [...HTML_AND_ASTRO, "**/*.vue", "**/*.svelte"] as const;
+
+// stylelint resolves a name from the repository, and the kit's peers sit beside the kit rather than under every repository it lints.
+function peer(name: string): string {
+  return fileURLToPath(import.meta.resolve(name));
+}
+
+const CONVENTION_CHANGES = {
+  "no-descending-specificity": null,
+  "property-no-vendor-prefix": [true, { disableFix: true, ignoreProperties: ["-webkit-user-select"] }],
+} as const satisfies Rules;
+
+const SELECTOR_COMPLEXITY = {
+  "selector-max-specificity": "0,3,2",
+  "selector-max-compound-selectors": 3,
+} as const satisfies Rules;
+
+const COLOUR_FUNCTIONS = ["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color"] as const;
+
+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"] },
+} as const satisfies Rules;
+
+const REFUSED_BASELINE = '@avi2dg/checks/stylelint: set baseline to "widely", "newly" or a year such as 2024';
+
+const REFUSED_TOKENS = "@avi2dg/checks/stylelint: set tokens to the globs of the token files, or false to leave the design token rules off";
+
+function baselineTarget(baseline: unknown): BaselineTarget {
+  if (baseline === "widely" || baseline === "newly") return baseline;
+  if (typeof baseline === "number" && Number.isInteger(baseline)) return baseline;
+  throw new TypeError(REFUSED_BASELINE);
+}
+
+function isGlobList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((glob) => typeof glob === "string" && glob !== "");
+}
+
+function tokenFiles(tokens: unknown): readonly string[] {
+  if (tokens === false) return [];
+  if (isGlobList(tokens) && tokens.length > 0) return tokens;
+  throw new TypeError(REFUSED_TOKENS);
+}
+
+const BASELINE_RULE = "plugin/use-baseline";
+
+// A repository's Baseline entry replaces the kit's option object whole, so the @property pass goes into whichever entry lands.
+function passProperty(entry: Rules[string]): unknown {
+  if (entry === null || entry === undefined) return entry;
+  const [primary, options = {}] = Array.isArray(entry) ? entry : [entry];
+  const ignored: unknown = Reflect.get(options, "ignoreAtRules") ?? [];
+  if (!Array.isArray(ignored)) return entry;
+  return [primary, { ...options, ignoreAtRules: ["property", ...ignored] }];
+}
+
+function designTokens(files: readonly string[]): Required<Pick<Config, "rules" | "overrides">> {
+  if (files.length === 0) return { rules: {}, overrides: [] };
+  const off = Object.fromEntries(Object.keys(DESIGN_TOKENS).map((rule) => [rule, null]));
+  return { rules: DESIGN_TOKENS, overrides: [{ files: [...files], rules: off }] };
+}
+
+// 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 {
+  const available = baselineTarget(baseline);
+  const tokenRules = designTokens(tokenFiles(tokens));
+  const merged: Rules = {
+    ...CONVENTION_CHANGES,
+    ...SELECTOR_COMPLEXITY,
+    [BASELINE_RULE]: [true, { available }],
+    ...tokenRules.rules,
+    ...rules,
+  };
+  return {
+    ...rest,
+    extends: [peer("stylelint-config-standard")],
+    plugins: [peer("stylelint-plugin-use-baseline")],
+    rules: { ...merged, [BASELINE_RULE]: passProperty(merged[BASELINE_RULE]) },
+    overrides: [
+      { files: [...MARKUP], customSyntax: peer("postcss-html") },
+      { files: [...HTML_AND_ASTRO], rules: { "declaration-block-single-line-max-declarations": null } },
+      ...tokenRules.overrides,
+      ...overrides,
+    ],
+  };
+}