stylelint-plugin-rhythmguard 3.15.0 → 3.16.1

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,30 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.16.1] - 2026-11-01
10
+
11
+ ### Fixed
12
+
13
+ - `npx rhythmguard` and `rhythmguard audit` work again in a project without Stylelint. 3.16.0 made `stylelint` an optional peer, so npm stopped installing it next to the CLI, and the audit, which runs the rules through Stylelint's API to read stylesheets, failed with `Cannot find package 'stylelint'`. The 3.16.0 entry was wrong to say `rhythmguard audit` never loaded Stylelint: it loads it with a dynamic `import()`, which the contract test did not see. The `rhythmguard` package now depends on `stylelint`, so `npx rhythmguard` brings it. The plugin's own `rhythmguard` command, which an ESLint-only project also gets, now says to run `npm install --save-dev stylelint` instead of printing a module path. The contract test now reads dynamic imports.
14
+
15
+ ### Changed
16
+
17
+ - The post-publish smoke test installs all three packages from npm, each in a clean project with only what its README asks for: `rhythmguard` alone, audited on a CSS file and a JSX file, and `eslint-plugin-rhythmguard` with ESLint and no Stylelint. Before this it covered only `stylelint-plugin-rhythmguard`, and 3.16.0 passed it with the CLI broken.
18
+
19
+ ## [3.16.0] - 2026-11-01
20
+
21
+ ### Changed
22
+
23
+ - `stylelint` is now an optional peer dependency. An ESLint-only project no longer installs it: `eslint-plugin-rhythmguard` adds 8 packages to an ESLint 10 install, where 3.15.0 added 101, Stylelint among them. Projects that run the Stylelint rules already list `stylelint` themselves, and npm still checks its version range when it is installed. The ESLint rules and `rhythmguard audit` never loaded Stylelint; a contract test now keeps every module outside `src/rules` from importing it.
24
+ - `rhythmguard doctor` recognises an ESLint-only setup. When Stylelint is neither installed nor configured and an ESLint config references Rhythmguard, it checks ESLint and that config instead of failing with "stylelint not installed".
25
+
26
+ ### Added
27
+
28
+ - `scripts/bench/tailwind-compare.mjs` reruns the competitor test: one TSX file of spacing classes through eslint-plugin-better-tailwindcss, eslint-plugin-tailwindcss, @shadcn/lint, the Tailwind CLI `canonicalize` and this rule, at pinned versions. The ESLint package README opens its comparison with the result, including the gap every tool shares: no tool, this one included, checks a v4 step such as `p-3.25` against a scale. The repository README puts Stylelint and ESLint side by side as the two ways in.
29
+ - The ESLint rules are tested under Oxlint. A CI job runs `tailwind-class-use-scale` through Oxlint 1.88.0 JS plugins on TSX, for findings and `--fix`, and runs every `.oxlintrc.json` sample in the docs. The Oxlint config is now in `docs/TAILWIND.md` and the rule docs, next to the ESLint one, with the alpha and no-Vue-or-Svelte caveat. ([#327](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/327))
30
+ - The ESLint package README shows how to adopt the rule on an existing codebase with ESLint's bulk suppressions (`--suppress-rule`, `--prune-suppressions`, ESLint 9.24 or newer), with no Rhythmguard baseline format.
31
+ - `rhythmguard --version` and `-v` print the version from `package.json` and exit 0. Before this, both were treated as unknown commands: the CLI printed the help text and exited 1. Both flags are listed under Options in `rhythmguard --help`. ([#326](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/326))
32
+
9
33
  ## [3.15.0] - 2026-10-30
10
34
 
11
35
  ### Added
package/CONTRIBUTING.md CHANGED
@@ -80,7 +80,7 @@ If your shell's npm registry is overridden by a corporate `.npmrc`, add `--regis
80
80
 
81
81
  ### Pull requests from forks
82
82
 
83
- 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.
83
+ 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 runs after merge, and the quiet benchmark runs only on `main`: it clones 57 repositories, so for any change under `src/` run `npm run bench:quiet -- --check` yourself before asking for review. When a pull request is merged or closed, its queued and running workflow runs are cancelled.
84
84
 
85
85
  ## What is frozen until 4.0
86
86
 
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026
3
+ Copyright (c) 2026 Petri Lahdelma
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -7,13 +7,13 @@
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=3150)](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=3161)](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
 
14
- 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.
14
+ 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 ESLint or Oxlint, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
15
15
 
16
- 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. Nor does it judge type for reading: whether a measure, a fluid heading or a number column works for the reader is the job of [Measured Type](#type-pair-it-with-measured-type).
16
+ 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 ESLint plugin 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. Nor does it judge type for reading: whether a measure, a fluid heading or a number column works for the reader is the job of [Measured Type](#type-pair-it-with-measured-type).
17
17
 
18
18
  ## Start here
19
19
 
@@ -27,7 +27,9 @@ No install, no config. It detects your stack and token files, infers your spacin
27
27
  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/quickstart.gif?v=1" width="100%" alt="Terminal recording: npx stylelint-plugin-rhythmguard on Bootstrap v6-dev detects the stack, infers the 13-step spacing scale from scss/_config.scss, reports 20 off-scale values in CSS and prints a .stylelintrc.json to paste" />
28
28
  </p>
29
29
 
30
- Then:
30
+ Then add the linter you already run. Most projects need one; a project with both stylesheets and class strings can run both.
31
+
32
+ ### Stylesheets: Stylelint
31
33
 
32
34
  ```bash
33
35
  npm install --save-dev stylelint stylelint-plugin-rhythmguard
@@ -47,7 +49,9 @@ That enables `rhythmguard/use-scale` on spacing properties with the default 4px
47
49
  }
48
50
  ```
49
51
 
50
- 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.
52
+ ### Class strings: ESLint or Oxlint
53
+
54
+ For Tailwind class strings in JSX, TSX, Vue, Svelte or Astro, use [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme). It needs no Stylelint. It is the same rules as `stylelint-plugin-rhythmguard/eslint`, so either import works, and CI tests them under Oxlint's JS plugins too. How it compares with the other Tailwind lint rules: [the comparison](packages/eslint-plugin-rhythmguard#why-this-and-not-a-ban).
51
55
 
52
56
  ```bash
53
57
  npm install --save-dev eslint eslint-plugin-rhythmguard
@@ -140,7 +144,7 @@ The two do not overlap. Rhythmguard reports the `13px` padding and the `17px` he
140
144
 
141
145
  ## Compatibility
142
146
 
143
- 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 has been checked by hand on 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, 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 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).
144
148
 
145
149
  ## Contributing and support
146
150
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stylelint-plugin-rhythmguard",
3
- "version": "3.15.0",
3
+ "version": "3.16.1",
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"
@@ -168,6 +168,9 @@
168
168
  "postcss-scss": {
169
169
  "optional": true
170
170
  },
171
+ "stylelint": {
172
+ "optional": true
173
+ },
171
174
  "stylelint-config-tailwindcss": {
172
175
  "optional": true
173
176
  },
@@ -181,7 +184,7 @@
181
184
  "postcss-value-parser": "^4.2.0"
182
185
  },
183
186
  "devDependencies": {
184
- "@anthropic-ai/sdk": "^0.137.0",
187
+ "@anthropic-ai/sdk": "^1.0.0",
185
188
  "@eslint/js": "^10.0.0",
186
189
  "@types/node": "^22.20.1",
187
190
  "c8": "^12.0.0",
@@ -200,5 +203,8 @@
200
203
  "publishConfig": {
201
204
  "access": "public"
202
205
  },
203
- "license": "MIT"
206
+ "license": "MIT",
207
+ "overrides": {
208
+ "minimatch": "^11.0.3"
209
+ }
204
210
  }
@@ -32,6 +32,26 @@ function resolveScssSyntax() {
32
32
  return scssSyntaxCache;
33
33
  }
34
34
 
35
+ /**
36
+ * Stylelint is an optional peer, so an ESLint-only project can reach this
37
+ * without it. The `rhythmguard` package depends on it; this package's own
38
+ * command says what to install instead of failing on a module path.
39
+ */
40
+ async function loadStylelint() {
41
+ try {
42
+ return (await import('stylelint')).default;
43
+ } catch (error) {
44
+ if (error && error.code === 'ERR_MODULE_NOT_FOUND' && /'stylelint'/.test(error.message)) {
45
+ throw new Error(
46
+ 'Auditing stylesheets needs Stylelint, which this project does not have. '
47
+ + 'Install it with: npm install --save-dev stylelint',
48
+ { cause: error },
49
+ );
50
+ }
51
+ throw error;
52
+ }
53
+ }
54
+
35
55
  async function runStylelintAudit(cssFiles, options) {
36
56
  if (cssFiles.length === 0) {
37
57
  const empty = [];
@@ -42,7 +62,7 @@ async function runStylelintAudit(cssFiles, options) {
42
62
  return empty;
43
63
  }
44
64
 
45
- const { default: stylelint } = await import('stylelint');
65
+ const stylelint = await loadStylelint();
46
66
  const rules = {
47
67
  'rhythmguard/use-scale': [
48
68
  true,
package/src/cli/doctor.js CHANGED
@@ -13,7 +13,8 @@ const HELP = `Usage: rhythmguard doctor
13
13
 
14
14
  Validate the Rhythmguard setup in the current directory: Stylelint, its config,
15
15
  the rules it references, .rhythmguardrc.json, token sources and the baseline.
16
- Exits 1 when a check fails.
16
+ In a project that uses Rhythmguard through ESLint only (no Stylelint), checks
17
+ ESLint and its config instead of Stylelint's. Exits 1 when a check fails.
17
18
 
18
19
  Options:
19
20
  --help Show this help message
@@ -46,27 +47,29 @@ function warn(msg) {
46
47
  process.stdout.write(`! ${msg}\n`);
47
48
  }
48
49
 
50
+ function installedVersion(name) {
51
+ try {
52
+ return require(require.resolve(`${name}/package.json`, { paths: [cwd] })).version;
53
+ } catch {
54
+ return null;
55
+ }
56
+ }
57
+
49
58
  // Check 1: Stylelint installed
50
59
  function checkStylelint() {
51
- try {
52
- const stylelintPkg = require.resolve('stylelint/package.json', {
53
- paths: [cwd],
54
- });
55
- const version = require(stylelintPkg).version;
60
+ const version = installedVersion('stylelint');
61
+ if (version) {
56
62
  pass(`stylelint installed (v${version})`);
57
63
  return true;
58
- } catch {
59
- fail(
60
- 'stylelint not installed',
61
- 'Run: npm install --save-dev stylelint',
62
- );
63
- return false;
64
64
  }
65
+ fail(
66
+ 'stylelint not installed',
67
+ 'Run: npm install --save-dev stylelint',
68
+ );
69
+ return false;
65
70
  }
66
71
 
67
- // Check 2: Config found
68
- function findConfig() {
69
- const configFiles = [
72
+ const STYLELINT_CONFIG_FILES = [
70
73
  '.stylelintrc',
71
74
  '.stylelintrc.json',
72
75
  '.stylelintrc.js',
@@ -77,28 +80,56 @@ function findConfig() {
77
80
  'stylelint.config.js',
78
81
  'stylelint.config.cjs',
79
82
  'stylelint.config.mjs',
80
- ];
83
+ ];
84
+
85
+ const ESLINT_CONFIG_FILES = [
86
+ 'eslint.config.js',
87
+ 'eslint.config.mjs',
88
+ 'eslint.config.cjs',
89
+ 'eslint.config.ts',
90
+ 'eslint.config.mts',
91
+ 'eslint.config.cts',
92
+ '.eslintrc',
93
+ '.eslintrc.js',
94
+ '.eslintrc.cjs',
95
+ '.eslintrc.json',
96
+ '.eslintrc.yml',
97
+ '.eslintrc.yaml',
98
+ ];
99
+
100
+ function readPackageJson() {
101
+ try {
102
+ return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
103
+ } catch {
104
+ return null;
105
+ }
106
+ }
81
107
 
82
- for (const file of configFiles) {
108
+ // The first config file present, or the package.json key; { label, path, content } or null.
109
+ function locateConfig(files, packageKey) {
110
+ for (const file of files) {
83
111
  const fullPath = path.join(cwd, file);
84
112
  if (fs.existsSync(fullPath)) {
85
- pass(`config found (${file})`);
86
- return fullPath;
113
+ return { content: fs.readFileSync(fullPath, 'utf8'), label: file, path: fullPath };
87
114
  }
88
115
  }
116
+ const pkg = readPackageJson();
117
+ if (pkg && pkg[packageKey]) {
118
+ return {
119
+ content: JSON.stringify(pkg[packageKey]),
120
+ label: `package.json ${packageKey} key`,
121
+ path: path.join(cwd, 'package.json'),
122
+ };
123
+ }
124
+ return null;
125
+ }
89
126
 
90
- // Check package.json
91
- const pkgPath = path.join(cwd, 'package.json');
92
- if (fs.existsSync(pkgPath)) {
93
- try {
94
- const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
95
- if (pkg.stylelint) {
96
- pass('config found (package.json stylelint key)');
97
- return pkgPath;
98
- }
99
- } catch {
100
- // ignore
101
- }
127
+ // Check 2: Config found
128
+ function findConfig() {
129
+ const found = locateConfig(STYLELINT_CONFIG_FILES, 'stylelint');
130
+ if (found) {
131
+ pass(`config found (${found.label})`);
132
+ return found.path;
102
133
  }
103
134
 
104
135
  fail(
@@ -377,6 +408,26 @@ function checkRhythmguardBaseline(audit) {
377
408
  }
378
409
  }
379
410
 
411
+ // An ESLint-only setup: Rhythmguard's ESLint rules, no Stylelint installed or configured.
412
+ function eslintOnlyConfig() {
413
+ if (installedVersion('stylelint') || locateConfig(STYLELINT_CONFIG_FILES, 'stylelint')) {
414
+ return null;
415
+ }
416
+ const found = locateConfig(ESLINT_CONFIG_FILES, 'eslintConfig');
417
+ return found && found.content.includes('rhythmguard') ? found : null;
418
+ }
419
+
420
+ function checkEslintSetup(config) {
421
+ const version = installedVersion('eslint');
422
+ if (version) {
423
+ pass(`eslint installed (v${version})`);
424
+ } else {
425
+ fail('eslint not installed', 'Run: npm install --save-dev eslint');
426
+ }
427
+ pass(`ESLint config references rhythmguard (${config.label})`);
428
+ skip('Stylelint checks skipped (ESLint-only setup)');
429
+ }
430
+
380
431
  function run() {
381
432
  // Doctor takes no arguments; --help prints the usage, anything else is refused (#286).
382
433
  for (const arg of process.argv.slice(3)) {
@@ -390,12 +441,18 @@ function run() {
390
441
 
391
442
  process.stdout.write('\nRhythmguard Doctor\n\n');
392
443
 
393
- const stylelintOk = checkStylelint();
394
- const configPath = findConfig();
395
- const configContent = checkConfigReferences(configPath);
396
- checkTokenPattern(configContent);
397
- checkTailwindConfig(configContent);
398
- checkCustomSyntax(configContent);
444
+ const eslintConfig = eslintOnlyConfig();
445
+ let stylelintOk = true;
446
+ if (eslintConfig) {
447
+ checkEslintSetup(eslintConfig);
448
+ } else {
449
+ stylelintOk = checkStylelint();
450
+ const configPath = findConfig();
451
+ const configContent = checkConfigReferences(configPath);
452
+ checkTokenPattern(configContent);
453
+ checkTailwindConfig(configContent);
454
+ checkCustomSyntax(configContent);
455
+ }
399
456
  checkRhythmguardConfig();
400
457
 
401
458
  process.stdout.write('\n');
package/src/cli/index.js CHANGED
@@ -16,6 +16,7 @@ Commands:
16
16
 
17
17
  Options:
18
18
  --help Show this help message; after a command, that command's help
19
+ --version Print the version; -v does the same
19
20
 
20
21
  Examples:
21
22
  npx rhythmguard
@@ -36,6 +37,12 @@ function main() {
36
37
  process.exit(0);
37
38
  }
38
39
 
40
+ if (command === '--version' || command === '-v') {
41
+ // Read the version from this package's own manifest, so it cannot drift from package.json.
42
+ process.stdout.write(`${require('../../package.json').version}\n`);
43
+ process.exit(0);
44
+ }
45
+
39
46
  if (!command || command === 'quickstart') {
40
47
  require('./quickstart').run();
41
48
  } else if (command === 'audit') {