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 +27 -0
- package/CONTRIBUTING.md +7 -7
- package/README.md +16 -2
- package/package.json +2 -2
- package/src/core/token-packages.json +24 -0
- package/src/core/token-sources.js +28 -2
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.
|
|
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.
|
|
69
|
-
npm run test:pack-smoke # pack
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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
|
[](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
|
|
10
|
-
[](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
|
|
11
11
|
[](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
|
|
12
12
|
[](./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
|
|
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.
|
|
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.
|
|
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
|
|
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;
|