stylelint-plugin-rhythmguard 3.18.0 → 3.20.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.
Files changed (58) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.md +4 -4
  4. package/SECURITY.md +14 -0
  5. package/agents/claude-code/SKILL.md +14 -1
  6. package/agents/copilot/{copilot-instructions.md → rhythmguard.instructions.md} +7 -1
  7. package/agents/cursor/rhythmguard.mdc +5 -3
  8. package/package.json +2 -2
  9. package/src/audit/args.js +30 -8
  10. package/src/audit/baseline.js +44 -2
  11. package/src/audit/codemod.js +2 -0
  12. package/src/audit/config.js +7 -0
  13. package/src/audit/contract.js +131 -17
  14. package/src/audit/next-steps.js +86 -0
  15. package/src/audit/non-authored.js +1 -0
  16. package/src/audit/render-github.js +52 -15
  17. package/src/audit/render-markdown.js +58 -17
  18. package/src/audit/render-text.js +76 -6
  19. package/src/audit/render-utils.js +14 -0
  20. package/src/audit/report.js +235 -10
  21. package/src/audit/scan/files.js +5 -0
  22. package/src/audit/scan/stylesheets.js +63 -59
  23. package/src/audit/scan/templates.js +2 -0
  24. package/src/audit/shared.js +7 -1
  25. package/src/audit/token-chains.js +1 -0
  26. package/src/cli/audit.js +20 -11
  27. package/src/cli/doctor.js +853 -237
  28. package/src/cli/first-run.js +210 -0
  29. package/src/cli/index.js +25 -1
  30. package/src/cli/index.mjs +3 -0
  31. package/src/cli/init.js +75 -26
  32. package/src/cli/quickstart.js +109 -118
  33. package/src/cli/scale.js +223 -0
  34. package/src/configs/recommended.js +3 -1
  35. package/src/configs/strict.js +3 -1
  36. package/src/configs/tailwind.js +15 -0
  37. package/src/core/decisions.js +18 -5
  38. package/src/core/fs-cache.js +1 -0
  39. package/src/core/options.js +2 -1
  40. package/src/core/scale-inference.js +72 -52
  41. package/src/core/tailwind-class-analysis.js +56 -13
  42. package/src/core/token-index.js +55 -14
  43. package/src/core/token-map.js +140 -88
  44. package/src/core/token-sources.js +461 -40
  45. package/src/core/value-nodes.js +4 -2
  46. package/src/eslint/class-context.js +330 -0
  47. package/src/eslint/literal-spans.js +5 -4
  48. package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
  49. package/src/presets/default-scale.js +42 -0
  50. package/src/presets/scales.js +6 -1
  51. package/src/rules/no-offscale-transform/index.js +17 -5
  52. package/src/rules/prefer-token/index.js +51 -15
  53. package/src/rules/use-scale/index.js +7 -4
  54. package/types/__checks__/consumer.ts +17 -0
  55. package/types/__checks__/eslint-config.ts +5 -0
  56. package/types/audit.d.ts +42 -3
  57. package/types/cli.d.ts +77 -1
  58. package/types/shared.d.ts +10 -0
@@ -1,9 +1,8 @@
1
1
  'use strict';
2
2
 
3
3
  const { readJsonFile } = require('./json');
4
- const { parseTokenValueLength } = require('./token-sources');
4
+ const { conditionsOfNode, parseTokenValueLength, scopeOfNode } = require('./token-sources');
5
5
 
6
- const { spawnSync } = require('node:child_process');
7
6
  const fs = require('node:fs');
8
7
  const path = require('node:path');
9
8
  const {
@@ -53,7 +52,27 @@ function displayOrigin(file) {
53
52
  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
54
53
  }
55
54
 
56
- function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize, origins = null, origin = null) {
55
+ /**
56
+ * The tokens one map source offers for each key, before they reach the map.
57
+ * A key collects the tokens whose value is written that way (`exact`) apart
58
+ * from the tokens that only convert to it (`converted`: a 1rem token under the
59
+ * 16px key), so a token in the literal's own unit is preferred, as the token
60
+ * index does.
61
+ */
62
+ function createCollector() {
63
+ return new Map();
64
+ }
65
+
66
+ function collect(collector, key, token, exact) {
67
+ if (!collector.has(key)) {
68
+ collector.set(key, { converted: new Set(), exact: new Set(), last: token });
69
+ }
70
+ const entry = collector.get(key);
71
+ (exact ? entry.exact : entry.converted).add(token);
72
+ entry.last = token;
73
+ }
74
+
75
+ function addLengthValueMapping(collector, rawLength, tokenReference, baseFontSize, origins = null, origin = null) {
57
76
  if (typeof rawLength !== 'string') {
58
77
  return;
59
78
  }
@@ -75,15 +94,49 @@ function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize, ori
75
94
  // Keyed by the signed value: a -8px token stands for -8px, never for 8px
76
95
  // (issue #221). prefer-token negates a positive token for a negative literal.
77
96
  const normalizedRaw = formatLength(parsed.number, parsed.unit || 'px');
78
- map[normalizedRaw] = token;
97
+ collect(collector, normalizedRaw, token, true);
79
98
 
80
99
  const px = toPx(parsed.number, parsed.unit, baseFontSize);
81
100
  if (px !== null) {
82
- map[`${px}px`] = token;
101
+ const pxKey = `${px}px`;
102
+ collect(collector, pxKey, token, pxKey === normalizedRaw);
83
103
  }
84
104
  }
85
105
 
86
- function mergeExplicitTokenMap(target, source) {
106
+ /**
107
+ * The tokens a collected key stands for: the ones written in its unit when
108
+ * there are any, the converted ones otherwise. Sorted, so messages are stable.
109
+ */
110
+ function candidatesOf(entry) {
111
+ const chosen = entry.exact.size > 0 ? entry.exact : entry.converted;
112
+ return [...chosen].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
113
+ }
114
+
115
+ /**
116
+ * Write one source's keys into the map. A key one token holds maps to that
117
+ * token. A key several tokens hold is a guess either way, so it is recorded
118
+ * in `ambiguous` with every candidate and no fix writes it (fix-06); the map
119
+ * keeps a token under the key only so the set of keys (which scale inference
120
+ * reads) is unchanged. A later source replaces an earlier one key by key.
121
+ * `accept` may skip a key entirely, leaving earlier sources in charge of it.
122
+ */
123
+ function applyCollector(map, ambiguous, collector, accept = () => true) {
124
+ for (const [key, entry] of collector) {
125
+ const candidates = candidatesOf(entry);
126
+ if (!accept(candidates)) {
127
+ continue;
128
+ }
129
+ if (candidates.length === 1) {
130
+ map[key] = candidates[0];
131
+ delete ambiguous[key];
132
+ } else {
133
+ map[key] = entry.last;
134
+ ambiguous[key] = candidates;
135
+ }
136
+ }
137
+ }
138
+
139
+ function mergeExplicitTokenMap(target, source, ambiguous = {}) {
87
140
  if (!isPlainObject(source)) {
88
141
  return target;
89
142
  }
@@ -94,12 +147,13 @@ function mergeExplicitTokenMap(target, source) {
94
147
  }
95
148
 
96
149
  target[raw] = tokenReference;
150
+ delete ambiguous[raw];
97
151
  }
98
152
 
99
153
  return target;
100
154
  }
101
155
 
102
- function walkTokenGroup(map, group, prefix, baseFontSize, origins, origin) {
156
+ function walkTokenGroup(collector, group, prefix, baseFontSize, origins, origin) {
103
157
  for (const [key, value] of Object.entries(group)) {
104
158
  const tokenName = `${prefix}-${key}`;
105
159
 
@@ -109,26 +163,28 @@ function walkTokenGroup(map, group, prefix, baseFontSize, origins, origin) {
109
163
 
110
164
  // Leaf node with $value (DTCG)
111
165
  if (typeof value.$value === 'string') {
112
- addLengthValueMapping(map, value.$value, tokenName, baseFontSize, origins, origin);
166
+ addLengthValueMapping(collector, value.$value, tokenName, baseFontSize, origins, origin);
113
167
  continue;
114
168
  }
115
169
 
116
170
  // Leaf node with value (Style Dictionary)
117
171
  if (typeof value.value === 'string') {
118
- addLengthValueMapping(map, value.value, tokenName, baseFontSize, origins, origin);
172
+ addLengthValueMapping(collector, value.value, tokenName, baseFontSize, origins, origin);
119
173
  continue;
120
174
  }
121
175
 
122
176
  // Nested group: recurse deeper
123
- walkTokenGroup(map, value, tokenName, baseFontSize, origins, origin);
177
+ walkTokenGroup(collector, value, tokenName, baseFontSize, origins, origin);
124
178
  }
125
179
  }
126
180
 
127
181
  function mergeTokenMapFromFile({
182
+ ambiguous = {},
128
183
  baseFontSize,
129
184
  currentMap,
130
185
  origins = null,
131
186
  tokenMapFile,
187
+ warnings = [],
132
188
  }) {
133
189
  if (!tokenMapFile) {
134
190
  return currentMap;
@@ -136,13 +192,15 @@ function mergeTokenMapFromFile({
136
192
 
137
193
  const resolvedPath = path.resolve(process.cwd(), tokenMapFile);
138
194
  if (!fs.existsSync(resolvedPath)) {
195
+ warnings.push(`Token map file not found: ${tokenMapFile}`);
139
196
  return currentMap;
140
197
  }
141
198
 
142
199
  let parsed;
143
200
  try {
144
201
  parsed = readJsonFile(resolvedPath);
145
- } catch {
202
+ } catch (error) {
203
+ warnings.push(`Unable to parse token map file ${tokenMapFile}: ${error.message}`);
146
204
  return currentMap;
147
205
  }
148
206
 
@@ -153,6 +211,7 @@ function mergeTokenMapFromFile({
153
211
  const nextMap = {
154
212
  ...currentMap,
155
213
  };
214
+ const collector = createCollector();
156
215
  const origin = displayOrigin(resolvedPath);
157
216
 
158
217
  for (const [entryKey, entryValue] of Object.entries(parsed)) {
@@ -161,7 +220,7 @@ function mergeTokenMapFromFile({
161
220
  const valueAsLength = parseLengthToken(entryValue);
162
221
 
163
222
  if (keyAsLength) {
164
- nextMap[entryKey] = entryValue;
223
+ collect(collector, entryKey, entryValue, true);
165
224
  if (origins && !origins[entryValue]) {
166
225
  origins[entryValue] = origin;
167
226
  }
@@ -169,38 +228,48 @@ function mergeTokenMapFromFile({
169
228
  }
170
229
 
171
230
  if (valueAsLength) {
172
- addLengthValueMapping(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
231
+ addLengthValueMapping(collector, entryValue, entryKey, baseFontSize, origins, origin);
173
232
  }
174
233
 
175
234
  continue;
176
235
  }
177
236
 
178
237
  if (typeof entryValue === 'number') {
179
- addLengthValueMapping(nextMap, `${entryValue}px`, entryKey, baseFontSize, origins, origin);
238
+ addLengthValueMapping(collector, `${entryValue}px`, entryKey, baseFontSize, origins, origin);
180
239
  continue;
181
240
  }
182
241
 
183
242
  if (isPlainObject(entryValue)) {
184
243
  // Style Dictionary format: { value: "16px" }
185
244
  if (typeof entryValue.value === 'string') {
186
- addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize, origins, origin);
245
+ addLengthValueMapping(collector, entryValue.value, entryKey, baseFontSize, origins, origin);
187
246
  continue;
188
247
  }
189
248
 
190
249
  // W3C DTCG format: { $value: "16px", $type: "dimension" }
191
250
  if (typeof entryValue.$value === 'string') {
192
- addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize, origins, origin);
251
+ addLengthValueMapping(collector, entryValue.$value, entryKey, baseFontSize, origins, origin);
193
252
  continue;
194
253
  }
195
254
 
196
255
  // Nested group: recurse (e.g. { spacing: { 4: { $value: "16px" } } })
197
- walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
256
+ walkTokenGroup(collector, entryValue, entryKey, baseFontSize, origins, origin);
198
257
  }
199
258
  }
200
259
 
260
+ applyCollector(nextMap, ambiguous, collector);
201
261
  return nextMap;
202
262
  }
203
263
 
264
+ /**
265
+ * Whether a custom property declaration is defined everywhere: at the root
266
+ * (`:root`, `html`, `@theme`) and outside every `@media`, `@supports` and
267
+ * `@container` block.
268
+ */
269
+ function declaredEverywhere(decl) {
270
+ return scopeOfNode(decl) === 'root' && conditionsOfNode(decl).length === 0;
271
+ }
272
+
204
273
  function mergeTokenMapFromCssCustomProperties({
205
274
  baseFontSize,
206
275
  currentMap,
@@ -226,24 +295,39 @@ function mergeTokenMapFromCssCustomProperties({
226
295
  const px = parsed ? toPx(parsed.number, parsed.unit, baseFontSize) : null;
227
296
  const key = px === null ? `raw:${decl.value.trim()}` : `px:${formatLength(px, 'px')}`;
228
297
  if (!valuesByProp.has(decl.prop)) {
229
- valuesByProp.set(decl.prop, { decl, keys: new Set() });
298
+ valuesByProp.set(decl.prop, { decl, everywhere: false, keys: new Set() });
230
299
  }
231
- valuesByProp.get(decl.prop).keys.add(key);
300
+ const entry = valuesByProp.get(decl.prop);
301
+ entry.keys.add(key);
302
+ entry.everywhere = entry.everywhere || declaredEverywhere(decl);
232
303
  });
233
304
 
234
- for (const { decl, keys } of valuesByProp.values()) {
235
- if (keys.size > 1) {
305
+ const collector = createCollector();
306
+ const everywhere = new Set();
307
+ for (const entry of valuesByProp.values()) {
308
+ if (entry.keys.size > 1) {
236
309
  continue;
237
310
  }
238
311
 
239
- const parsed = parseTokenValueLength(decl.value);
312
+ const parsed = parseTokenValueLength(entry.decl.value);
240
313
  if (!parsed || parsed.number === 0) {
241
314
  continue;
242
315
  }
243
316
 
244
- addLengthValueMapping(nextMap, decl.value, `var(${decl.prop})`, baseFontSize, origins, origin);
317
+ const token = `var(${entry.decl.prop})`;
318
+ if (entry.everywhere) {
319
+ everywhere.add(token);
320
+ }
321
+ addLengthValueMapping(collector, entry.decl.value, token, baseFontSize, origins, origin);
245
322
  }
246
323
 
324
+ // A value two tokens hold, or one held by a token that is not defined
325
+ // everywhere (a `.card` token, a token under `@media`), is left out of the
326
+ // map. prefer-token's token index then names every candidate defined where
327
+ // the value sits and writes one only when it is the only one (css-08,
328
+ // fix-02).
329
+ applyCollector(nextMap, {}, collector, (candidates) => candidates.length === 1 && everywhere.has(candidates[0]));
330
+
247
331
  return nextMap;
248
332
  }
249
333
 
@@ -275,6 +359,9 @@ function extractTailwindSpacing(config) {
275
359
  };
276
360
  }
277
361
 
362
+ // Why a Tailwind config could not be loaded, by resolved path (cq-05).
363
+ const tailwindLoadErrors = new Map();
364
+
278
365
  function loadTailwindSpacingFromRequire(resolvedPath) {
279
366
  try {
280
367
  const loaded = require(resolvedPath);
@@ -283,63 +370,8 @@ function loadTailwindSpacingFromRequire(resolvedPath) {
283
370
  : loaded;
284
371
 
285
372
  return extractTailwindSpacing(config);
286
- } catch {
287
- return null;
288
- }
289
- }
290
-
291
- function loadTailwindSpacingFromDynamicImport(resolvedPath) {
292
- const script = [
293
- 'const { pathToFileURL } = require("node:url");',
294
- '(async () => {',
295
- ' try {',
296
- ' const configPath = process.argv[1];',
297
- ' const loaded = await import(pathToFileURL(configPath).href);',
298
- ' const config = loaded && typeof loaded.default === "object" ? loaded.default : loaded;',
299
- ' if (!config || typeof config !== "object" || Array.isArray(config)) {',
300
- ' process.stdout.write("{}");',
301
- ' return;',
302
- ' }',
303
- ' const theme = config.theme && typeof config.theme === "object" && !Array.isArray(config.theme)',
304
- ' ? config.theme',
305
- ' : null;',
306
- ' if (!theme) {',
307
- ' process.stdout.write("{}");',
308
- ' return;',
309
- ' }',
310
- ' const spacing = theme.spacing && typeof theme.spacing === "object" && !Array.isArray(theme.spacing)',
311
- ' ? theme.spacing',
312
- ' : {};',
313
- ' const extendSpacing = theme.extend && typeof theme.extend === "object" && !Array.isArray(theme.extend) &&',
314
- ' theme.extend.spacing && typeof theme.extend.spacing === "object" && !Array.isArray(theme.extend.spacing)',
315
- ' ? theme.extend.spacing',
316
- ' : {};',
317
- ' process.stdout.write(JSON.stringify({ ...spacing, ...extendSpacing }));',
318
- ' } catch {',
319
- ' process.exit(1);',
320
- ' }',
321
- '})();',
322
- ].join('\n');
323
-
324
- const child = spawnSync(process.execPath, ['-e', script, resolvedPath], {
325
- encoding: 'utf8',
326
- timeout: 5000,
327
- });
328
-
329
- if (child.error || child.status !== 0) {
330
- return null;
331
- }
332
-
333
- if (typeof child.stdout !== 'string' || child.stdout.trim() === '') {
334
- return null;
335
- }
336
-
337
- try {
338
- const parsed = JSON.parse(child.stdout);
339
- return isPlainObject(parsed)
340
- ? parsed
341
- : null;
342
- } catch {
373
+ } catch (error) {
374
+ tailwindLoadErrors.set(resolvedPath, error && error.message ? error.message.split('\n')[0] : String(error));
343
375
  return null;
344
376
  }
345
377
  }
@@ -349,18 +381,21 @@ function loadTailwindSpacing(resolvedPath) {
349
381
  return tailwindSpacingCache.get(resolvedPath);
350
382
  }
351
383
 
352
- const spacing =
353
- loadTailwindSpacingFromRequire(resolvedPath) ||
354
- loadTailwindSpacingFromDynamicImport(resolvedPath);
384
+ // require() loads CommonJS and ES module configs alike on every supported Node
385
+ // (require(esm) is on from 20.19). A config that uses top-level await cannot be
386
+ // required and is not read; point scaleSources at the built CSS instead.
387
+ const spacing = loadTailwindSpacingFromRequire(resolvedPath);
355
388
 
356
389
  tailwindSpacingCache.set(resolvedPath, spacing);
357
390
  return spacing;
358
391
  }
359
392
 
360
393
  function mergeTokenMapFromTailwindSpacing({
394
+ ambiguous = {},
361
395
  currentMap,
362
396
  origins = null,
363
397
  tailwindConfigPath,
398
+ warnings = [],
364
399
  }) {
365
400
  if (!tailwindConfigPath) {
366
401
  return currentMap;
@@ -368,10 +403,16 @@ function mergeTokenMapFromTailwindSpacing({
368
403
 
369
404
  const resolvedPath = path.resolve(process.cwd(), tailwindConfigPath);
370
405
  if (!fs.existsSync(resolvedPath)) {
406
+ warnings.push(`Tailwind config not found: ${tailwindConfigPath}`);
371
407
  return currentMap;
372
408
  }
373
409
 
374
410
  const spacing = loadTailwindSpacing(resolvedPath);
411
+ if (tailwindLoadErrors.has(resolvedPath)) {
412
+ // A config that throws used to read as "no known token" (cq-05).
413
+ warnings.push(`Tailwind config ${tailwindConfigPath} could not be loaded: ${tailwindLoadErrors.get(resolvedPath)}`);
414
+ return currentMap;
415
+ }
375
416
  if (!isPlainObject(spacing) || Object.keys(spacing).length === 0) {
376
417
  return currentMap;
377
418
  }
@@ -379,6 +420,7 @@ function mergeTokenMapFromTailwindSpacing({
379
420
  const nextMap = {
380
421
  ...currentMap,
381
422
  };
423
+ const collector = createCollector();
382
424
 
383
425
  for (const [key, value] of Object.entries(spacing)) {
384
426
  if (typeof value !== 'string') {
@@ -391,12 +433,14 @@ function mergeTokenMapFromTailwindSpacing({
391
433
  }
392
434
 
393
435
  const normalizedRaw = formatLength(parsed.number, parsed.unit || 'px');
394
- nextMap[normalizedRaw] = `theme(spacing.${key})`;
395
- if (origins && !origins[nextMap[normalizedRaw]]) {
396
- origins[nextMap[normalizedRaw]] = displayOrigin(resolvedPath);
436
+ const token = `theme(spacing.${key})`;
437
+ collect(collector, normalizedRaw, token, true);
438
+ if (origins && !origins[token]) {
439
+ origins[token] = displayOrigin(resolvedPath);
397
440
  }
398
441
  }
399
442
 
443
+ applyCollector(nextMap, ambiguous, collector);
400
444
  return nextMap;
401
445
  }
402
446
 
@@ -404,18 +448,24 @@ function mergeTokenMapFromTailwindSpacing({
404
448
  * The raw-length to token-reference map a rule fixes with. Pass `origins` to
405
449
  * also learn where each token reference came from (the token map file, the
406
450
  * stylesheet, the Tailwind config), keyed by the reference; an explicit
407
- * `tokenMap` entry has no origin.
451
+ * `tokenMap` entry has no origin. Pass `ambiguous` to learn the keys several
452
+ * tokens of one source hold, each with its candidates: those keys are never a
453
+ * fix (fix-06).
408
454
  */
409
455
  function buildEffectiveTokenMap({
456
+ ambiguous = {},
410
457
  options,
411
458
  origins = null,
412
459
  root,
413
460
  tokenRegex,
461
+ warnings = [],
414
462
  }) {
415
463
  let tokenMap = {};
416
464
 
417
465
  if (options.tokenMapFile) {
418
466
  tokenMap = mergeTokenMapFromFile({
467
+ ambiguous,
468
+ warnings,
419
469
  baseFontSize: options.baseFontSize,
420
470
  currentMap: tokenMap,
421
471
  origins,
@@ -435,6 +485,8 @@ function buildEffectiveTokenMap({
435
485
 
436
486
  if (options.tokenMapFromTailwindSpacing && options.tailwindConfigPath) {
437
487
  tokenMap = mergeTokenMapFromTailwindSpacing({
488
+ ambiguous,
489
+ warnings,
438
490
  currentMap: tokenMap,
439
491
  origins,
440
492
  tailwindConfigPath: options.tailwindConfigPath,
@@ -442,7 +494,7 @@ function buildEffectiveTokenMap({
442
494
  }
443
495
 
444
496
  // Explicit tokenMap applied last so it takes precedence over auto-derived tokens
445
- tokenMap = mergeExplicitTokenMap(tokenMap, options.tokenMap);
497
+ tokenMap = mergeExplicitTokenMap(tokenMap, options.tokenMap, ambiguous);
446
498
 
447
499
  return tokenMap;
448
500
  }