stylelint-plugin-rhythmguard 3.16.1 → 3.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,33 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.18.0] - 2026-11-05
10
+
11
+ ### Changed
12
+
13
+ - Stylelint 18 is supported: the peer range is `^16.7.0 || ^17.0.0 || ^18.0.0` in the plugin and in the `rhythmguard` CLI's dependency, so `npm install stylelint@18 stylelint-config-standard@41 stylelint-plugin-rhythmguard` resolves where it failed with ERESOLVE. No code changed; the full suite passes on 18.0.0. On a Node older than Stylelint 18 needs (22.22, 24.15 or 26), npm installs Stylelint 17 for `npx rhythmguard`. The README says how `use-scale` differs from 18's new `value-type-custom-property-required-list` and how to run both. Closes #168.
14
+ - The Stylelint floor is 16.7.0. On 16.0 to 16.6, Stylelint never read a rule's fix callback, so `--fix` kept every warning and changed nothing. A project on one of those versions gets a peer conflict when it upgrades and resolves it with `npm update stylelint` (any 16.x from 16.7 on). The floor suite now checks that a fix applies.
15
+ - CI and the release verify Stylelint 18 on Node 22, 24 and 26; the floor rows run 16.7.0. The pack and registry smoke tests install the plugin next to Stylelint 16.7.0, 17, and 18 with stylelint-config-standard 41 (18 is skipped on a Node it does not support), and the weekly job tests the newest Stylelint instead of the removed `next` tag.
16
+
17
+ ### Added
18
+
19
+ - `scale: "auto"` reads GitLab's spacing scale: Sass scalars named `$<namespace>-spacing-scale-<n>` count as a scale when a namespace holds at least four lengths, as `$gl-spacing-scale-1` to `$gl-spacing-scale-88` do in gitlab-ui. Other namespaced scalars, such as `$dropdown-spacer`, stay excluded. gitlab-ui's benchmark row is measured against that scale: 3 off-scale values, as before, but `-2px` is now on it and a 14px margin is found.
20
+ - `scale: "auto"` reads `@wikimedia/codex-design-tokens` when it is installed: the `--spacing-0` to `--spacing-400` ladder (0 to 64px). The named `--spacing-*` tokens are computed component values and are left out. Codex has no benchmark row, because its components and most of its consumers are written in Less, which the audit does not read (#175).
21
+
22
+ ### Changed
23
+
24
+ - Sass expressions evaluate `px-to-rem(<n>px)` as that length, in token files and in `use-scale` values. A second argument changes the base and is still skipped, as is any other function. A variable defined with it can now produce a finding where it was invisible before.
25
+
26
+ ## [3.17.0] - 2026-11-04
27
+
28
+ ### Added
29
+
30
+ - `scale: "auto"` reads WordPress's spacing scale when `@wordpress/base-styles` or `@wordpress/theme` is installed: the Sass `$grid-unit-05` to `$grid-unit-80` (4 to 64px) from `_variables.scss`, and `--wpds-dimension-gap-*` and `--wpds-dimension-padding-*` (4 to 40px) from `prebuilt/css/design-tokens.css`. The `--wpds-dimension-size-*` and `surface-*` tokens are sizes, not spacing, and are left out. Gutenberg's benchmark row is measured against both packages, as a Gutenberg maintainer pointed out in WordPress/gutenberg#82502: 34 off-scale values on `packages/components/src`, against 35 on the fallback, because 20px is a WordPress padding step.
31
+
32
+ ### Changed
33
+
34
+ - `npm run test:pack-smoke`, which CI and the release run before publishing, now packs `rhythmguard` and `eslint-plugin-rhythmguard` as well as the plugin, and runs on each tarball the same check the post-publish smoke runs from npm (`scripts/ci/smoke-checks.mjs`). Before this it packed only the plugin, so the 3.16.0 CLI failure could reach npm; with the CLI's `stylelint` dependency removed, the pack smoke now fails at `rhythmguard audit`.
35
+
9
36
  ## [3.16.1] - 2026-11-01
10
37
 
11
38
  ### Fixed
package/CONTRIBUTING.md CHANGED
@@ -47,7 +47,7 @@ Node 20.19 or newer; `.nvmrc` pins 22 for development, so `nvm use` picks it up.
47
47
  | `test/cli/` | a command as a user runs it, in a temp directory | `node --test test/cli/audit-cli.test.js` |
48
48
  | `test/api/` | the programmatic audit API | |
49
49
  | `test/contracts/` | what must stay true for consumers: package exports, CJS/ESM parity, layer rules, rule docs | `node --test test/contracts/architecture.test.js` |
50
- | `test/compat/` | the Stylelint 16.0.0 floor | `npm run test:compat-floor` |
50
+ | `test/compat/` | the Stylelint 16.7.0 floor | `npm run test:compat-floor` |
51
51
  | `test/bench/` | the benchmark and report scripts | |
52
52
 
53
53
  Put a new test where its subject lives. If it needs the real linter, it is a rule test; if it needs a temp directory and `spawnSync`, it is a CLI test; if it asserts something about the repository itself, it is a contract.
@@ -65,8 +65,8 @@ npm test # 600+ tests, on the Stylelint in the lockfile (17)
65
65
  Optional, depending on what you touched:
66
66
 
67
67
  ```bash
68
- npm run test:compat-floor # Stylelint 16.0.0, the oldest supported
69
- npm run test:pack-smoke # pack the tarball and install it in a temp project
68
+ npm run test:compat-floor # Stylelint 16.7.0, the oldest supported
69
+ npm run test:pack-smoke # pack all three packages and smoke-test each in a temp project
70
70
  npm run scales:validate # community scale JSON
71
71
  npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
72
72
  npm run build:agents # after editing the block in docs/FOR_AGENTS.md
@@ -74,7 +74,7 @@ npm run build:playground # after changing anything under src/ the rules us
74
74
  npm run bench:agents -- --dry-run --limit 4 # the agent eval pipeline, no API key needed
75
75
  ```
76
76
 
77
- The local gate runs on whatever Node you have installed; CI runs Node 20 and 22 against Stylelint 16.0.0, 16 and 17, Node 24 and 26 against Stylelint 17, the ESLint companion rules on ESLint 9, and once a week the full suite against Stylelint `next`. 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.
77
+ The local gate runs on whatever Node you have installed; CI runs Node 20 and 22 against Stylelint 16.7.0, 16 and 17, Node 22, 24 and 26 against Stylelint 18, the ESLint companion rules on ESLint 9, and once a week the full suite against the newest Stylelint (`next` while a major is in prerelease, else `latest`). 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.
78
78
 
79
79
  If your shell's npm registry is overridden by a corporate `.npmrc`, add `--registry https://registry.npmjs.org` to `npm ci` and prefix `test:pack-smoke` with `npm_config_registry=https://registry.npmjs.org`.
80
80
 
@@ -84,7 +84,7 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
84
84
 
85
85
  ## What is frozen until 4.0
86
86
 
87
- Rhythmguard is in a feature freeze until 4.0, which ships the week Stylelint 18.0.0 is released (plan: [`docs/COUNCIL_2027-2028.md`](./docs/COUNCIL_2027-2028.md)). Please do not start work on these without an issue where the maintainer has agreed to an exception:
87
+ Rhythmguard is in a feature freeze until 4.0 (plan: [`docs/COUNCIL_2027-2028.md`](./docs/COUNCIL_2027-2028.md), with the dates proposed in [`docs/PRODUCT_REVIEW_2026-11.md`](./docs/PRODUCT_REVIEW_2026-11.md)). Stylelint 18 support shipped in 3.18.0 without waiting for it. Please do not start work on these without an issue where the maintainer has agreed to an exception:
88
88
 
89
89
  - new rule options, property groups, presets, or default scales;
90
90
  - motion features and Tailwind class-name features beyond bug fixes;
@@ -119,10 +119,10 @@ Always welcome: bug fixes with a failing test, false-positive reports, token-sou
119
119
 
120
120
  ## Compatibility
121
121
 
122
- - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
122
+ - Stylelint `^16.7.0 || ^17.0.0 || ^18.0.0`. 16.7.0 is the first version that applies a rule's fix callback; CI runs the floor suite, fixes included, against it.
123
123
  - Node `>=20.19.0` until 4.0, which raises it to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
124
124
  - ESLint `>=8.0.0` for the companion rules; tested on 9 and 10.
125
- - Stylelint 18: the full suite passes on 18.0.0-next.0 and runs weekly against `next`; the peer range widens in the week 18.0.0 ships.
125
+ - Stylelint 18 needs Node ^22.22.2, ^24.15.0 or >=26; CI runs it on Node 22, 24 and 26, and `test/contracts/stylelint-18-pairing.test.js` runs the README's pairing with its new core rule there.
126
126
  - CommonJS and ESM entry points; every export has a declaration under `types/`.
127
127
  - 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.
128
128
 
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  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.
8
8
 
9
9
  [![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)
10
- [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3161)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
10
+ [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3180)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
11
11
  [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
12
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
13
13
 
@@ -144,7 +144,21 @@ The two do not overlap. Rhythmguard reports the `13px` padding and the `17px` he
144
144
 
145
145
  ## Compatibility
146
146
 
147
- 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 10, and is tested in CI on Oxlint 1.88.0. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `stylelint` is a peer you need only for the Stylelint rules and the stylesheet audit, so an ESLint-only project installs without it, and `npx rhythmguard` brings its own; `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, and Node 24 and 26 against 17.x; a weekly job runs the suite against Stylelint `next` (18.0.0-next.0 passes). Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
147
+ Stylelint 16.7 to 18. The floor is 16.7.0 because Stylelint reads a rule's fix callback from that version on; on 16.0 to 16.6 `--fix` changed nothing. 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)). Stylelint 18 needs Node 22.22, 24.15 or 26, and on an older Node npm installs Stylelint 17 for `npx rhythmguard`. The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9 and 10, and is tested in CI on Oxlint 1.88.0. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `stylelint` is a peer you need only for the Stylelint rules and the stylesheet audit, so an ESLint-only project installs without it, and `npx rhythmguard` brings its own; `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers (`stylelint-plugin-logical-css` itself still peers on Stylelint 17 or older). CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.7.0, 16.x and 17.x, and Node 22, 24 and 26 against 18.x; a weekly job runs the suite against the latest Stylelint. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
148
+
149
+ ### Stylelint 18's custom-property rule
150
+
151
+ Stylelint 18 added `value-type-custom-property-required-list`. It answers a different question from `use-scale`. The core rule says a length must be a custom property: it reports `16px` and a `1px` hairline the same way as `13px`, names no step, and `--fix` leaves the value alone. `use-scale` says which value is off your scale and which two steps are nearest, and `--fix` writes the nearest step; `prefer-token` names the token that holds the value; both read the scale from your token file. To move every length to a token over time, run both:
152
+
153
+ ```json
154
+ {
155
+ "plugins": ["stylelint-plugin-rhythmguard"],
156
+ "rules": {
157
+ "rhythmguard/use-scale": [true, { "scale": "auto" }],
158
+ "value-type-custom-property-required-list": [["length"], { "severity": "warning" }]
159
+ }
160
+ }
161
+ ```
148
162
 
149
163
  ## Contributing and support
150
164
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stylelint-plugin-rhythmguard",
3
- "version": "3.16.1",
3
+ "version": "3.18.0",
4
4
  "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.",
5
5
  "bin": {
6
6
  "rhythmguard": "src/cli/index.js"
@@ -160,7 +160,7 @@
160
160
  },
161
161
  "peerDependencies": {
162
162
  "postcss-scss": "^4.0.0",
163
- "stylelint": "^16.0.0 || ^17.0.0",
163
+ "stylelint": "^16.7.0 || ^17.0.0 || ^18.0.0",
164
164
  "stylelint-config-tailwindcss": "^1.0.1",
165
165
  "stylelint-plugin-logical-css": "^2.0.2"
166
166
  },
@@ -93,6 +93,30 @@
93
93
  "dist/units/units.custom-properties.css"
94
94
  ],
95
95
  "note": "--spacing-xs..2xl in px; Protocol's Sass $spacing-* come from the same package"
96
+ },
97
+ {
98
+ "name": "@wordpress/base-styles",
99
+ "files": [
100
+ "_variables.scss"
101
+ ],
102
+ "tokenPattern": "^\\$grid-unit-\\d+$",
103
+ "note": "WordPress names its spacing scale $grid-unit-05..80 (4 to 64px, multiples of $grid-unit)"
104
+ },
105
+ {
106
+ "name": "@wordpress/theme",
107
+ "files": [
108
+ "prebuilt/css/design-tokens.css"
109
+ ],
110
+ "tokenPattern": "^--wpds-dimension-(?:gap|padding)-",
111
+ "note": "--wpds-dimension-gap-* and --wpds-dimension-padding-* in px; size and surface tokens are not spacing"
112
+ },
113
+ {
114
+ "name": "@wikimedia/codex-design-tokens",
115
+ "files": [
116
+ "dist/theme-wikimedia-ui.css"
117
+ ],
118
+ "tokenPattern": "^--spacing-\\d+$",
119
+ "note": "Codex ladder --spacing-0..400 (0 to 64px); the named --spacing-* tokens are computed component values"
96
120
  }
97
121
  ]
98
122
  }
@@ -490,7 +490,7 @@ function customPropertyDeclarations(source, { lineComments = true } = {}) {
490
490
  /**
491
491
  * Sass variables and maps as token sources. Handles `$spacer: 1rem`, maps such
492
492
  * as `$spacers: (1: $spacer * .25, ...)` including nested maps, variable
493
- * references, `* / + -` arithmetic and `math.div()`. Anything it cannot
493
+ * references, `* / + -` arithmetic, `math.div()` and `px-to-rem()`. Anything it cannot
494
494
  * evaluate (function calls, strings, keywords, interpolated keys, cycles) is
495
495
  * skipped rather than guessed. Token names are `$name` or `$name.key.path`.
496
496
  */
@@ -530,6 +530,8 @@ function collectScssTokens(source, matchesKind, { lineComments = true } = {}) {
530
530
  // Namespaced maps such as GOV.UK's $govuk-spacing-points are only accepted
531
531
  // for the spacing kind, and only when they hold a real ladder (issue #86).
532
532
  const spacingKind = matchesKind('$spacing-probe');
533
+ // Scalars such as GitLab's $gl-spacing-scale-1..88 count the same way, per namespace (issue #167).
534
+ const namespacedScales = spacingKind ? collectNamespacedSpacingScales(declarations, resolveVariable) : new Set();
533
535
 
534
536
  for (const [name, raw] of declarations) {
535
537
  const tokenName = `$${name}`;
@@ -555,12 +557,32 @@ function collectScssTokens(source, matchesKind, { lineComments = true } = {}) {
555
557
  });
556
558
  continue;
557
559
  }
558
- push(tokenName, resolveVariable(name, new Set()));
560
+ push(tokenName, resolveVariable(name, new Set()), namespacedScales.has(name));
559
561
  }
560
562
 
561
563
  return tokens;
562
564
  }
563
565
 
566
+ /** The `<namespace>-spacing-scale-*` scalars whose namespace holds a real ladder. */
567
+ function collectNamespacedSpacingScales(declarations, resolveVariable) {
568
+ const byNamespace = new Map();
569
+ for (const [name, raw] of declarations) {
570
+ const match = isScssMap(raw) ? null : name.match(NAMESPACED_SPACING_SCALE);
571
+ const value = match ? resolveVariable(name, new Set()) : null;
572
+ if (!value) continue;
573
+ if (!byNamespace.has(match[1])) byNamespace.set(match[1], { lengths: new Set(), names: [] });
574
+ const entry = byNamespace.get(match[1]);
575
+ entry.names.push(name);
576
+ const formatted = formatScssValue(value);
577
+ if (/^-?\d*\.?\d+(?:px|rem|em)$/.test(formatted) && parseFloat(formatted) !== 0) entry.lengths.add(formatted);
578
+ }
579
+ const accepted = new Set();
580
+ for (const { lengths, names } of byNamespace.values()) {
581
+ if (lengths.size >= MIN_NAMESPACED_MAP_LENGTHS) names.forEach((name) => accepted.add(name));
582
+ }
583
+ return accepted;
584
+ }
585
+
564
586
  /**
565
587
  * A variable resolver over a Sass source text, for evaluating declaration
566
588
  * values: same-file declarations first, then `fallback(name)` for a length
@@ -594,6 +616,8 @@ function createScssVariableResolver(source, fallback = () => null) {
594
616
  /** `$<namespace>-spacing-points`, `$<ns>-space-scale`: one namespace segment before the anchor. */
595
617
  const NAMESPACED_SPACING_MAP = /^\$[a-z0-9]+-(?:space|spacing|spacer)s?(?:-|$)/i;
596
618
  const MIN_NAMESPACED_MAP_LENGTHS = 4;
619
+ /** `$gl-spacing-scale-1`, `$gl-spacing-scale-11-5`: one namespace segment, then a numbered step. Names here carry no `$`. */
620
+ const NAMESPACED_SPACING_SCALE = /^([a-z0-9]+)-spacing-scale-\d/i;
597
621
 
598
622
  /**
599
623
  * The value of a Sass variable declaration starting at `start`: the text up to
@@ -915,6 +939,8 @@ function createScssParser(tokens, resolveVariable, stack) {
915
939
  const closing = next();
916
940
  if (!closing || closing.type !== 'op' || closing.value !== ')') return null;
917
941
  if (token.name === 'math.div' && args.length === 2) return combine(args[0], '/', args[1]);
942
+ // GitLab's $grid-size: px-to-rem(8px). One px length renders as that length; a second argument changes the base.
943
+ if (token.name === 'px-to-rem' && args.length === 1 && args[0]?.unit === 'px') return args[0];
918
944
  return null;
919
945
  }
920
946
  return null;