stylelint-plugin-rhythmguard 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.9.0] - 2026-10-15
+
+### Added
+
+- `scale: "auto"` reads `@mozilla-protocol/tokens` when it is installed: `--spacing-xs` to `--spacing-2xl` (4 to 48px) from `dist/units/units.custom-properties.css`. Mozilla Protocol's benchmark row is measured against that package at 7.0.0, as a Protocol contributor pointed out in mozilla/protocol#1132: 19 off-scale values, against 18 on the `rhythmic-4` fallback, because 12px is not a Protocol step and 48px is.
+
+### Fixed
+
+- `prefer-token` reads the token sources `use-scale` reads for `fixWith: "token"`: the linted stylesheet, `scaleSources`, the `audit.tokenSources` files in `.rhythmguardrc.json` and installed token packages ([#202](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/202)). Before, a token declared in a config token source was invisible to `prefer-token`, which then said no token held a value that one did; on one consumer, 478 of 611 baselined warnings were values an existing token holds. Both rules now resolve tokens through one function, so a token is known to both or to neither, and a contract test holds them to it. The fix writes such a token only when exactly one holds the value in the literal's unit, the same rule `fixWith: "token"` follows.
+- Tokens are matched to the property's kind. A `tokenPattern` such as `^--space-|^--radius-` no longer lets `padding: 1rem` be pointed at, or fixed to, `--radius-xl` because it also holds 16px. Radius, typography and motion tokens serve their own properties; spacing and size tokens serve each other's. Applies to `prefer-token` and to `fixWith: "token"` in `use-scale` and `no-offscale-transform`.
+- A rule's own `tokenPattern` applies to the token source files it reads as well as to the stylesheet, so `--radius-*` tokens in a config token source are found when the pattern asks for them.
+- The audit no longer hangs on template files that contain an unclosed quote followed by escape-dense source. The Tailwind class-string scanner found string literals with a regex whose alternation was ambiguous on every backslash, so from an apostrophe in a comment or a quote inside a regex literal it backtracked exponentially over the `\{ \[ \(` of the next regex literal; on the Ace editor's `mode-alda.js` (10 KB, vendored by a MediaWiki skin) one `rhythmguard audit` ran for eleven hours before it was killed, and Bootswatch's audit took longer than three minutes. The finder is now a single linear pass: an escape never closes a literal, a `'` or `"` literal that reaches a line break is not a literal, a backtick literal may span lines. Both repositories audit in seconds. The benchmark gained five findings that an unclosed quote had been hiding (four in Ghost's `input-group.tsx`, one in Cal.com's `Button.tsx`).
+- The audit no longer throws `All input files were ignored because of the ignore pattern` when a project's own `.stylelintignore` excludes every stylesheet the walk found. The files are counted as `scanned.stylelintIgnored` in the JSON contract and shown in text and Markdown output, so a clean report cannot hide that nothing was audited.
+
+### Messages
+
+Message text changes are listed here, so teams that key a warning baseline on message text know which warnings will reappear as resolved-plus-new pairs (see [#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
+
+- `prefer-token`, when a token in a config token source, `scaleSources` or an installed token package holds the value: was `No known token holds this value; use the nearest token or add one.`, now `Use var(--token) (path/to/tokens.css).` When a token in another unit holds it, the message names that token and the fix leaves the literal.
+- `prefer-token`, when several tokens hold the value: was `No known token holds this value; ...`, now `Use one of the tokens that hold it: var(--a) or var(--b).`
+- Unchanged: the message for a value no token holds, and every `use-scale` message.
+
+### Changed
+
+- The post-publish smoke waits for the version through `npm view --prefer-online`, the client that will install it, instead of the raw packument; for 3.8.0 the packument listed the version a minute before `npm install` could resolve it and the smoke failed.
+- The quiet benchmark installs the token packages maintainers named as the home of their scale. A manifest row lists them under `tokenPackages` with a pinned version; `npm run bench:quiet` installs them once under `benchmarks/quiet/packages/` with install scripts disabled and passes the allowlisted token files to the audit as explicit sources, so the row is measured against the ladder the maintainers pointed at instead of the `rhythmic-4` fallback or a set of consumer tokens. Carbon (`@carbon/layout`), Primer CSS and Primer React (`@primer/primitives`), mittwald Flow (`@mittwald/flow-design-tokens`) and AdminLTE (`bootstrap`) are measured this way; the SAP rows stay unmeasured because their theming package carries no ladder. The State of Spacing edition marks these rows `installed` and counts them.
+- PatternFly's fourteen benchmark findings are labelled by review: four in a vendored Font Awesome partial and ten in documentation example CSS, none in component SCSS, as the reply in patternfly/patternfly#8579 said. Per-repo labels live in `benchmarks/quiet/labels/`.
+- New README banner for 3.8.0. GitHub shows the transparent SVG; npmjs.com, which renders the README on a white page, gets the non-transparent PNG (`assets/rhythmguard-banner.png`): the release job swaps the banner line with `scripts/ci/npm-readme.mjs` just before `npm publish`, and a contract test fails if the banner line is not found exactly once. The npm page changes with the next published version.
+- `rhythmguard` and `eslint-plugin-rhythmguard` are on npm (3.8.0, first published by hand on 2026-09-27). `npx rhythmguard` now works in a project that has installed nothing, and the README's first command and ESLint setup use the two packages. Later releases publish them from `release.yml` once each has a trusted publisher and `PUBLISH_COMPANIONS` is set.
+
 ## [3.8.0] - 2026-09-18
 
 ### Added

package/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Report a false positive.** A finding your team considers wrong is the most valuable report we get. It is how percentages and hairlines stopped being findings. Open a [false-positive report](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/new?template=false-positive.yml) with the CSS or class string and your config. No fix required.
 
-**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions. The same results feed the dated [State of Spacing](./docs/STATE_OF_SPACING.md) editions, so every repository you add widens that report.
+**Add a repository to the quiet benchmark.** The benchmark audits public design systems and fails CI when the findings change. Adding a repo is one JSON entry in `benchmarks/quiet/repos.json` plus `npm run bench:quiet -- --only <name>` to create its snapshot. Systems with tokens in unusual places are the most useful additions. When the scale ships in an npm package rather than in the repository, list it under `tokenPackages` with a pinned version (the package must be in `src/core/token-packages.json`); the bench installs it and measures the row against that ladder. The same results feed the dated [State of Spacing](./docs/STATE_OF_SPACING.md) editions, so every repository you add widens that report.
 
 **Review a drift list.** Each benchmark repo has a list of findings that heuristics call real drift. Labelling them as real or as an allowance in `benchmarks/quiet/labels/<repo>.json` with a one-line reason turns a heuristic number into a reviewed one, and any systematic pattern you find becomes a candidate default.
 
@@ -16,6 +16,8 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Contribute a community scale.** JSON files in `scales/community/`, scaffolded with `npm run scales:add -- --name my-team-scale --base 8 --steps 0,4,8,12,16,24,32` and checked with `npm run scales:validate`. Spec and policy in [`docs/COMMUNITY_SCALES.md`](./docs/COMMUNITY_SCALES.md).
 
+The plan for the next nine months is in [`ROADMAP.md`](./ROADMAP.md), and every item there is an issue labelled [`roadmap`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/roadmap) with a milestone. Items labelled `decision` are open questions with the evidence that will settle them; a comment with evidence is a contribution.
+
 Issues labelled [`good first issue`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/good%20first%20issue) are scoped for a first PR. [`help wanted`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/help%20wanted) marks work the maintainer would like a second pair of hands on. If you want to work on something larger, open an issue first so we can agree the shape before you write code.
 
 ## Getting set up
@@ -27,7 +29,7 @@ npm ci
 npm test
 ```
 
-Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about ten seconds. They are grouped by what they prove:
+Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about fifteen seconds. They are grouped by what they prove:
 
 | Folder | Proves | Run one |
 | --- | --- | --- |
@@ -48,7 +50,7 @@ Run these before you push. They are what CI runs, so a green local run means a g
 ```bash
 npm run lint        # eslint
 npm run typecheck   # the published TypeScript declarations against a consumer file and the examples
-npm test            # 200+ tests, Stylelint 16
+npm test            # 300+ tests, on the Stylelint in the lockfile (17)
 ```
 
 Optional, depending on what you touched:
@@ -59,6 +61,8 @@ npm run test:pack-smoke        # pack the tarball and install it in a temp proje
 npm run scales:validate        # community scale JSON
 npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
 npm run build:agents           # after editing the block in docs/FOR_AGENTS.md
+npm run build:playground       # after changing anything under src/ the rules use
+npm run bench:agents -- --dry-run --limit 4   # the agent eval pipeline, no API key needed
 ```
 
 The local gate runs on whatever Node you have installed; CI runs Node 20 and 22. Node 20.19 is the floor, so avoid features that arrived in Node 21 or later. Glob patterns for `node --test` were one such feature, and they took a release run down.
@@ -67,7 +71,7 @@ If your shell's npm registry is overridden by a corporate `.npmrc`, add `--regis
 
 ### Pull requests from forks
 
-CI for this repository runs on self-hosted runners for pushes and same-repo branches. For pull requests from forks a separate job runs on GitHub-hosted runners with Node 22 and current Stylelint 16, covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
+CI for this repository runs on self-hosted runners for pushes and same-repo branches. For pull requests from forks a separate job runs on GitHub-hosted runners with Node 22 and the Stylelint in the lockfile (17), covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
 
 ## Where things live
 
@@ -96,7 +100,8 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
 ## Compatibility
 
 - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
-- Node `>=20.19.0`.
+- Node `>=20.19.0` until 4.0, which raises it to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
+- ESLint `>=8.0.0` for the companion rules; tested on 9.
 - CommonJS and ESM entry points; every export has a declaration under `types/`.
 - Three runtime dependencies: `known-css-properties`, `postcss` and `postcss-value-parser`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here. `test/contracts/architecture.test.js` fails if a runtime import is not declared.
 
@@ -106,7 +111,7 @@ The maintainer aims to respond to issues and PRs within a week. Small PRs merge
 
 ## Releases
 
-Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. The checklist covers cutting a release while the farm is down. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
+Maintainer-run. Bump `package.json`, the two companion packages under `packages/` and `CHANGELOG.md` to the same version, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. The checklist covers cutting a release while the farm is down. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
 
 ## Benchmarking performance
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=12" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.png?v=13" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -7,18 +7,18 @@
 Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=380)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=390)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 
 Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS and SCSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
 
-What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). Pair it with a color linter if you need one; do not expect one tool to do both.
+What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). It reads CSS and SCSS; Less and CSS-in-JS are not read. Pair it with a color linter if you need one; do not expect one tool to do both.
 
 ## Start here
 
 ```bash
-npx stylelint-plugin-rhythmguard
+npx rhythmguard
 ```
 
 No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. This is the whole run on Bootstrap's `v6-dev` branch, unedited:
@@ -47,11 +47,15 @@ That enables `rhythmguard/use-scale` on spacing properties with the default 4px
 }
 ```
 
-For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion. It is the same rules under two names: `stylelint-plugin-rhythmguard/eslint` if you already have this package, or [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme) on its own.
+For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion, [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme). It is the same rules as `stylelint-plugin-rhythmguard/eslint`, so either import works. The rules also run under Oxlint's JS plugins.
+
+```bash
+npm install --save-dev eslint eslint-plugin-rhythmguard
+```
 
 ```js
 // eslint.config.js
-import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';
+import rhythmguard from 'eslint-plugin-rhythmguard';
 
 export default [
   {
@@ -80,6 +84,8 @@ Every rule validates its options up front. Unknown option names and wrong shapes
 
 ## Audit before you enforce
 
+With the package installed, the `rhythmguard` command is available to `npx`:
+
 ```bash
 npx rhythmguard audit ./src --format markdown
 npx rhythmguard audit ./src --write-baseline
@@ -101,14 +107,15 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block, installable with `npx rhythmguard init --agents all` for Claude Code, Cursor and Copilot
 - [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
-- [Agent evals](docs/AGENT_EVALS.md): does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control
+- [Agent evals](docs/AGENT_EVALS.md): does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control. First edition (2026-10-10): every model fixed every finding in one round with or without the findings; fixing from findings cost Sonnet 5 less than half as much
 - [Architecture](docs/ARCHITECTURE.md): the layers, the rule kit, the invariants and where each is enforced
-- [Product direction](docs/STRATEGY_2026-09.md)
+- [Roadmap](ROADMAP.md): what is planned from October 2026 to June 2027, and the checkpoint that decides the pace
+- [Product analysis, September 2026](docs/STRATEGY_2026-09.md): the market data behind the roadmap
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/) runs the real rules, bundled for the browser, on CSS or SCSS you paste; `scale: "auto"`, tokens and fixes included, and a test proves it reports what Stylelint reports
 
 ## Compatibility
 
-Stylelint 16 and 17. Node 20.19 or newer. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
+Stylelint 16 and 17. Node 20.19 or newer; Node 20 itself is end of life, and 4.0 raises the floor to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)). The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9, and has been checked by hand on ESLint 10 and Oxlint 1.85. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
 
 ## Contributing and support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -158,18 +158,18 @@
     "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.126.0",
-    "@eslint/js": "^9.39.5",
+    "@anthropic-ai/sdk": "^0.133.0",
+    "@eslint/js": "^10.0.0",
     "@types/node": "^22.20.1",
     "c8": "^12.0.0",
-    "esbuild": "^0.25.10",
-    "eslint": "^9.39.5",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.0.0",
     "postcss-scss": "^4.0.9",
-    "stylelint": "^16.15.0",
+    "stylelint": "^17.0.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2",
     "stylelint-scales": "^5.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.0"
   },
   "engines": {
     "node": ">=20.19.0"

package/src/audit/config.js

@@ -45,7 +45,7 @@ function loadAuditConfig(parsed) {
   try {
     config = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
   } catch (err) {
-    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`);
+    throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`, { cause: err });
   }
 
   if (!config || typeof config !== 'object' || Array.isArray(config)) {

package/src/audit/contract.js

@@ -26,7 +26,7 @@ function collectTokenContract({
   const matchesKind = createTokenKindMatcher(tokenKind);
 
   for (const filePath of cssFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -235,6 +235,7 @@ function buildReport({
   scanScope,
   scssFiles = 0,
   scssSkipped = 0,
+  stylelintIgnored = 0,
   templateFiles,
   tailwindFindings,
   tokenCandidateMinCount,
@@ -308,6 +309,7 @@ function buildReport({
       cssFiles: cssFiles.length,
       scssFiles,
       scssSkipped,
+      stylelintIgnored,
       templateFiles: templateFiles.length,
       totalFiles,
     },

package/src/audit/render-markdown.js

@@ -27,6 +27,7 @@ function renderMarkdown(report) {
     `| Template files scanned | ${report.templateFilesScanned} |`,
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
+    ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
     `| Files with issues | ${report.filesWithIssues} |`,
     `| Total findings | ${report.totalWarnings} |`,
     `| Scale cleanliness | ${report.scaleCleanliness}% |`,

package/src/audit/render-text.js

@@ -21,6 +21,7 @@ function renderText(report) {
     `  Template files scanned   ${String(report.templateFilesScanned).padStart(4)}`,
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`  SCSS files scanned       ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`  SCSS files skipped       ${String(report.scanned.scssSkipped).padStart(4)}  (install postcss-scss to audit them)`] : []),
+    ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`  Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)}  (not audited)`] : []),
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
   ];

package/src/audit/report.js

@@ -89,6 +89,7 @@ async function createAuditReport(options) {
     scanScope,
     scssFiles: cssResults.scssFiles || 0,
     scssSkipped: cssResults.scssSkipped || 0,
+    stylelintIgnored: cssResults.stylelintIgnored || 0,
     tailwindFindings: decided.tailwindFindings,
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,

package/src/audit/scan/files.js

@@ -80,7 +80,7 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
   const args = parsed.staged
     ? ['diff', '--name-only', '--cached', '--diff-filter=ACMR', '--']
     : ['diff', '--name-only', '--diff-filter=ACMR', parsed.since, '--'];
-  let output = '';
+  let output;
 
   try {
     output = execFileSync('git', args, {
@@ -90,7 +90,7 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
     });
   } catch (err) {
     const stderr = err.stderr ? String(err.stderr).trim() : err.message;
-    throw new Error(`Unable to read changed files from git: ${stderr}`);
+    throw new Error(`Unable to read changed files from git: ${stderr}`, { cause: err });
   }
 
   const cssFiles = [];

package/src/audit/scan/stylesheets.js

@@ -77,7 +77,10 @@ async function runStylelintAudit(cssFiles, options) {
   const results = [];
 
   if (plainFiles.length > 0) {
+    // A project's own .stylelintignore may exclude every file we pass; that is
+    // a count to report, not a reason for the audit to throw.
     const result = await stylelint.lint({
+      allowEmptyInput: true,
       files: plainFiles,
       config: {
         plugins: [pluginPath],
@@ -92,6 +95,7 @@ async function runStylelintAudit(cssFiles, options) {
     const scssSyntax = resolveScssSyntax();
     if (scssSyntax) {
       const result = await stylelint.lint({
+        allowEmptyInput: true,
         files: scssFiles,
         config: {
           customSyntax: scssSyntax,
@@ -107,6 +111,10 @@ async function runStylelintAudit(cssFiles, options) {
 
   results.scssFiles = scssFiles.length;
   results.scssSkipped = scssSkipped;
+  // Stylelint returns no result at all for a file its ignore file excludes, so
+  // the difference between what was passed and what came back is that count.
+  const linted = plainFiles.length + scssFiles.length - scssSkipped;
+  results.stylelintIgnored = Math.max(0, linted - results.length);
   return results;
 }
 

package/src/audit/scan/templates.js

@@ -18,7 +18,7 @@ function collectTailwindFindings(templateFiles, options) {
   const findings = [];
 
   for (const filePath of templateFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -64,7 +64,7 @@ function collectTailwindMotionFindings(templateFiles, options) {
   const findings = [];
 
   for (const filePath of templateFiles) {
-    let source = '';
+    let source;
     try {
       source = fs.readFileSync(filePath, 'utf8');
     } catch {
@@ -115,17 +115,51 @@ function buildTailwindMotionFindingText(token, analysis) {
   return `Unexpected Tailwind arbitrary motion duration "${token}". Use duration scale values.`;
 }
 
+/**
+ * Linear scan for string literals. A regex did this before, and from every
+ * quote that never closes (an apostrophe in a comment, a quote inside a regex
+ * literal) it backtracked to the end of the file; on a 3.5 MB minified editor
+ * bundle that took hours. This walks the source once: an escape never closes a
+ * literal, a ' or " literal that reaches a line break is not a literal (the
+ * language agrees), and a backtick literal may span lines.
+ */
 function findStringLiterals(source) {
   const literals = [];
-  const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
-  let match;
-
-  while ((match = literalPattern.exec(source)) !== null) {
-    literals.push({
-      quote: match[1],
-      value: match[2],
-      valueStart: match.index + 1,
-    });
+  const { length } = source;
+  let index = 0;
+
+  while (index < length) {
+    const quote = source[index];
+    if (quote !== '"' && quote !== "'" && quote !== '`') {
+      index += 1;
+      continue;
+    }
+
+    const valueStart = index + 1;
+    let cursor = valueStart;
+    let closed = false;
+    while (cursor < length) {
+      const char = source[cursor];
+      if (char === '\\') {
+        cursor += 2;
+        continue;
+      }
+      if (char === quote) {
+        closed = true;
+        break;
+      }
+      if (quote !== '`' && char === '\n') {
+        break;
+      }
+      cursor += 1;
+    }
+
+    if (closed) {
+      literals.push({ quote, value: source.slice(valueStart, cursor), valueStart });
+      index = cursor + 1;
+    } else {
+      index = valueStart;
+    }
   }
 
   return literals;

package/src/configs/embed.js

@@ -7,8 +7,8 @@
  * spacing tokens (scaleSources, .rhythmguardrc.json token sources, the
  * stylesheet's custom properties, a Tailwind config, then rhythmic-4).
  * No `extends`, no dependency beyond this plugin, and the shape is frozen for
- * the life of the 2.x line so a config that embeds it never changes behaviour
- * on a minor bump.
+ * the life of a major version so a config that embeds it never changes
+ * behaviour on a minor bump.
  */
 module.exports = {
   plugins: ['stylelint-plugin-rhythmguard'],

package/src/core/scale-inference.js

@@ -201,12 +201,16 @@ function scaleFromSources(sources, baseFontSize) {
  * `.rhythmguardrc.json` token sources and installed token packages. The same
  * places scale inference reads, in the same order.
  */
-function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenRegex }) {
+function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenPattern = null, tokenRegex }) {
   const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
   const sources = [...scaleSources, ...rcTokenSources(process.cwd()), ...discoverTokenPackages(process.cwd())];
-  const parsed = parseSourcesCached(sources, baseFontSize);
-  if (parsed) {
-    for (const [token, definition] of parsed.definitions) {
+  // A rule's own tokenPattern (`^--space-|^--radius-`) also applies to the
+  // files it reads, on top of the spacing names, unless a source sets its own.
+  const withPattern = tokenPattern
+    ? sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source }))
+    : [];
+  for (const parsed of [parseSourcesCached(sources, baseFontSize), parseSourcesCached(withPattern, baseFontSize)]) {
+    for (const [token, definition] of parsed ? parsed.definitions : []) {
       if (!definitions.has(token)) {
         definitions.set(token, definition);
       }

package/src/core/token-index.js

@@ -1,7 +1,45 @@
 'use strict';
 
+const { PROPERTY_GROUP_PATTERNS } = require('./css-vocabulary');
 const { fixedLengthValue, numbersEqual, toPx } = require('./length');
-const { parseTokenValueLength } = require('./token-sources');
+const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
+
+// Dedicated kinds first: a name like --radius-space-1 is a radius token.
+const TOKEN_KINDS = ['radius', 'typography', 'motion', 'size', 'spacing'].map((kind) => [kind, createTokenKindMatcher(kind)]);
+
+// Which token kinds may stand in for a property of each group. Spacing and size
+// share tokens in many systems (Open Props --size-*, mittwald --size-px--*);
+// radius, type and motion tokens serve only their own properties.
+const ACCEPTED_KINDS = Object.freeze({
+  motion: ['motion'],
+  radius: ['radius'],
+  size: ['size', 'spacing'],
+  spacing: ['spacing', 'size'],
+  typography: ['typography'],
+});
+
+/** The kind a token's name declares, or null when the name says nothing. */
+function tokenKindOf(token) {
+  const found = TOKEN_KINDS.find(([, matches]) => matches(token));
+  return found ? found[0] : null;
+}
+
+function propertyGroupOf(prop) {
+  const lower = String(prop || '').toLowerCase();
+  const found = Object.entries(PROPERTY_GROUP_PATTERNS).find(([, patterns]) => patterns.some((pattern) => pattern.test(lower)));
+  return found ? found[0] : null;
+}
+
+/**
+ * Whether a token may be offered for a property: a padding never gets a radius
+ * token, even when both hold 16px and the token pattern admits both. A token
+ * whose name declares no kind, or a property outside every group, is allowed.
+ */
+function tokenFitsProperty(token, prop) {
+  const group = prop ? propertyGroupOf(prop) : null;
+  const kind = group ? tokenKindOf(String(token).replace(/^var\(\s*|\s*\)$/g, '')) : null;
+  return !group || !kind || ACCEPTED_KINDS[group].includes(kind);
+}
 
 /**
  * Which token a fix may write for a length. Strict on purpose: the token must
@@ -19,24 +57,37 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
       const unit = parsed.unit || 'px';
       const px = toPx(Math.abs(parsed.number), unit, baseFontSize);
       if (px === null || !Number.isFinite(px) || px === 0) continue;
-      index.push({ px, raw: String(raw).trim(), token: definition.token, unit });
+      const file = definition.files ? [...definition.files][0] : null;
+      index.push({ file: file && file !== 'stylesheet' ? file : null, px, raw: String(raw).trim(), token: definition.token, unit });
     }
   }
   return index;
 }
 
-function tokenForLength(index, px, unit) {
+/**
+ * Every custom property that holds a length, for one property. The shared
+ * resolver behind use-scale's `fixWith: "token"` and prefer-token, so the two
+ * rules always know the same tokens. Same unit first; with `anyUnit`, a token
+ * in another unit that holds the same px value counts when none matches the
+ * unit. Sorted, so messages are stable.
+ */
+function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {}) {
   const wanted = unit || 'px';
-  const candidates = new Set();
+  const sameUnit = new Set();
+  const otherUnit = new Set();
   for (const entry of index) {
-    if (entry.token.startsWith('--') && entry.unit === wanted && numbersEqual(entry.px, Math.abs(px))) {
-      candidates.add(entry.token);
+    if (!entry.token.startsWith('--') || !numbersEqual(entry.px, Math.abs(px)) || !tokenFitsProperty(entry.token, prop)) {
+      continue;
     }
+    (entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
   }
-  if (candidates.size !== 1) {
-    return null;
-  }
-  return `var(${[...candidates][0]})`;
+  const found = sameUnit.size > 0 || !anyUnit ? sameUnit : otherUnit;
+  return [...found].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+}
+
+function tokenForLength(index, px, unit, prop = null) {
+  const candidates = tokensForLength(index, px, unit, { prop });
+  return candidates.length === 1 ? `var(${candidates[0]})` : null;
 }
 
 /** A negative token reference that is still valid where it is written. */
@@ -54,9 +105,9 @@ function negateReplacement(replacement) {
  * The replacement text a length rule writes: the matching token when the
  * options ask for one and exactly one qualifies, otherwise the literal.
  */
-function replacementFor(parsedLength, nearestPx, options) {
+function replacementFor(parsedLength, nearestPx, options, prop = null) {
   if (options.fixWith === 'token' && options.tokenIndex) {
-    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px');
+    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px', prop);
     if (token) {
       return parsedLength.number < 0 ? negateReplacement(token) : token;
     }
@@ -76,7 +127,10 @@ function tokenHoldsNote(replacement, formattedNearest) {
 module.exports = {
   negateReplacement,
   replacementFor,
+  tokenFitsProperty,
   tokenHoldsNote,
   tokenForLength,
   tokenIndexFromDefinitions,
+  tokenKindOf,
+  tokensForLength,
 };

package/src/core/token-packages.json

@@ -86,6 +86,13 @@
         "dist/nhsuk/core/settings/_spacing.scss"
       ],
       "note": "$nhsuk-spacing-points map"
+    },
+    {
+      "name": "@mozilla-protocol/tokens",
+      "files": [
+        "dist/units/units.custom-properties.css"
+      ],
+      "note": "--spacing-xs..2xl in px; Protocol's Sass $spacing-* come from the same package"
     }
   ]
 }

package/src/core/token-sources.js

@@ -123,7 +123,7 @@ function parseTokenSources({
       continue;
     }
 
-    let tokens = [];
+    let tokens;
     const matchesSource = normalizedSource.tokenPattern
       ? createPatternMatcher(normalizedSource.tokenPattern, matchesKind)
       : matchesKind;
@@ -428,7 +428,7 @@ function createScssVariableResolver(source, fallback = () => null) {
     if (stack.has(name)) {
       return null;
     }
-    let value = null;
+    let value;
     if (declarations.has(name)) {
       stack.add(name);
       const raw = declarations.get(name);

package/src/rules/no-offscale-transform/index.js

@@ -69,7 +69,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     withResolvedScale(options, root);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex: new RegExp(options.tokenPattern) }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex: new RegExp(options.tokenPattern),
+        }),
         options.baseFontSize,
       );
     }
@@ -157,7 +163,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
 
           const fixedValue = options.fixToScale
-            ? replacementFor(parsedLength, nearest.nearest, options)
+            ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
             : null;
 
           report(node, nearest, unit, fixedValue);
@@ -181,7 +187,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         }
 
         const fixedValue = options.fixToScale
-          ? replacementFor(parsedLength, nearest.nearest, options)
+          ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
           : null;
 
         report(node, nearest, 'px', fixedValue);

package/src/rules/prefer-token/index.js

@@ -25,25 +25,40 @@ const {
 const { buildEffectiveTokenMap } = require('../../core/token-map');
 
 const {
+  collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
 
 const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
 const { validatePrimary, validatePreferTokenSecondaryOptions } = require('../validate');
 
-const { negateReplacement } = require('../../core/token-index');
+const {
+  negateReplacement,
+  tokenFitsProperty,
+  tokenIndexFromDefinitions,
+  tokensForLength,
+} = require('../../core/token-index');
 
 const ruleName = 'rhythmguard/prefer-token';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, replacement = null, origin = null, note = '') =>
+  rejected: (value, replacement = null, origin = null, note = '', candidates = []) =>
     `Unexpected raw scale value "${value}". ${replacement
       ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
-      : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
+      : candidates.length > 1
+        ? `Use one of the tokens that hold it: ${listTokens(candidates)}.`
+        : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
 });
 
+function listTokens(tokens) {
+  const references = tokens.map((token) => `var(${token})`);
+  return references.length > 1
+    ? `${references.slice(0, -1).join(', ')} or ${references[references.length - 1]}`
+    : references.join('');
+}
+
 function applyNegativeToken(replacement, parsedLength) {
   return !replacement || parsedLength.number >= 0 ? replacement : negateReplacement(replacement);
 }
@@ -74,6 +89,36 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
   return null;
 }
 
+/**
+ * The tokens use-scale's `fixWith: "token"` would see: the stylesheet,
+ * `scaleSources`, `.rhythmguardrc.json` token sources and installed token
+ * packages, filtered to the property's kind. One same-unit token is a fix; a
+ * token in another unit, or several tokens, are named but never written.
+ */
+function resolveFromIndex(tokenIndex, parsedLength, prop, options) {
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', options.baseFontSize);
+  if (px === null || tokenIndex.length === 0) {
+    return { candidates: [] };
+  }
+  const unit = parsedLength.unit || 'px';
+  const sameUnit = tokensForLength(tokenIndex, px, unit, { prop });
+  const candidates = sameUnit.length > 0 || options.unitStrategy !== 'convert'
+    ? sameUnit
+    : tokensForLength(tokenIndex, px, unit, { anyUnit: true, prop });
+  if (candidates.length !== 1) {
+    return { candidates };
+  }
+  const token = `var(${candidates[0]})`;
+  const entry = tokenIndex.find((item) => item.token === candidates[0]);
+  return {
+    candidates,
+    fixable: sameUnit.length === 1,
+    origin: entry ? entry.file : null,
+    replacement: applyNegativeToken(token, parsedLength),
+    token,
+  };
+}
+
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
     const valid = validatePrimary(result, ruleName, primary);
@@ -105,6 +150,17 @@ const ruleFunction = (primary, secondaryOptions) => {
       tokenRegex,
     });
 
+    const tokenIndex = tokenIndexFromDefinitions(
+      collectTokenDefinitions({
+        baseFontSize: options.baseFontSize,
+        root,
+        scaleSources: options.scaleSources,
+        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+        tokenRegex,
+      }),
+      options.baseFontSize,
+    );
+
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     root.walkDecls((decl) => {
@@ -121,10 +177,23 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, resolved = null) => {
-        const replacement = resolved ? resolved.replacement : null;
-        const origin = resolved ? origins[resolved.token] || null : null;
-        reportValueNode({ decl, message: messages.rejected(node.value, replacement, origin, options.note), node, replacement, result, ruleName });
+      const reportNode = (node, parsedLength) => {
+        const mapped = resolveTokenReplacement(tokenMap, node.value, parsedLength, options);
+        if (mapped && tokenFitsProperty(mapped.token, prop)) {
+          const origin = origins[mapped.token] || null;
+          reportValueNode({ decl, message: messages.rejected(node.value, mapped.replacement, origin, options.note), node, replacement: mapped.replacement, result, ruleName });
+          return;
+        }
+        const indexed = resolveFromIndex(tokenIndex, parsedLength, prop, options);
+        const named = indexed.replacement || null;
+        reportValueNode({
+          decl,
+          message: messages.rejected(node.value, named, indexed.origin || null, options.note, indexed.candidates),
+          node,
+          replacement: indexed.fixable ? named : null,
+          result,
+          ruleName,
+        });
       };
 
       const checkWordNode = (node, context) => {
@@ -190,7 +259,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        reportNode(node, resolveTokenReplacement(tokenMap, node.value, parsedLength, options));
+        reportNode(node, parsedLength);
         return true;
       };
 

package/src/rules/use-scale/index.js

@@ -136,7 +136,7 @@ function checkLengthValue({
     }
 
     const fixedValue = options.fixToScale && fixable
-      ? replacementFor(parsedLength, nearest.nearest, options)
+      ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
       : null;
 
     report(node.value, decl, node, nearest, fixedValue, unit, evaluated ? evaluatedNote(evaluated, options) : '');
@@ -160,7 +160,7 @@ function checkLengthValue({
   }
 
   const fixedValue = options.fixToScale && fixable
-    ? replacementFor(parsedLength, nearest.nearest, options)
+    ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
     : null;
 
   report(node.value, decl, node, nearest, fixedValue, 'px', evaluated ? evaluatedNote(evaluated, options) : '');
@@ -239,7 +239,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex,
+        }),
         options.baseFontSize,
       );
     }

package/types/audit.d.ts

@@ -68,6 +68,8 @@ export interface AuditScanned {
   scssFiles?: number;
   /** .scss files found but not audited because postcss-scss is not installed. */
   scssSkipped?: number;
+  /** Stylesheets Stylelint skipped because the project's own .stylelintignore excludes them. */
+  stylelintIgnored?: number;
   templateFiles: number;
   totalFiles?: number;
   [key: string]: unknown;