stylelint-plugin-rhythmguard 3.12.0 → 3.14.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 (48) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +1 -1
  3. package/package.json +23 -1
  4. package/src/audit/args.js +23 -4
  5. package/src/audit/baseline.js +15 -2
  6. package/src/audit/codemod.js +56 -5
  7. package/src/audit/config.js +2 -1
  8. package/src/audit/contract.js +3 -0
  9. package/src/audit/decisions.js +45 -16
  10. package/src/audit/render-markdown.js +22 -21
  11. package/src/audit/render-text.js +4 -0
  12. package/src/audit/render-utils.js +28 -1
  13. package/src/audit/report.js +16 -2
  14. package/src/audit/scan/files.js +139 -30
  15. package/src/audit/token-chains.js +4 -1
  16. package/src/audit/token-ladders.js +23 -2
  17. package/src/cli/doctor.js +58 -6
  18. package/src/cli/fix.js +7 -6
  19. package/src/cli/index.js +2 -2
  20. package/src/cli/init.js +41 -5
  21. package/src/cli/quickstart.js +46 -8
  22. package/src/configs/embed.js +2 -0
  23. package/src/configs/motion.js +1 -0
  24. package/src/configs/recommended.js +1 -0
  25. package/src/configs/strict.js +1 -0
  26. package/src/configs/tailwind.js +1 -0
  27. package/src/core/decisions.js +2 -1
  28. package/src/core/json.js +25 -0
  29. package/src/core/length.js +11 -0
  30. package/src/core/options.js +39 -20
  31. package/src/core/scale-inference.js +78 -23
  32. package/src/core/tailwind-class-analysis.js +3 -2
  33. package/src/core/token-map.js +2 -1
  34. package/src/core/token-sources.js +143 -14
  35. package/src/eslint/index.js +14 -8
  36. package/src/eslint/rules/tailwind-class-use-motion-scale.js +1 -0
  37. package/src/eslint/rules/tailwind-class-use-scale.js +1 -0
  38. package/src/rules/no-offscale-transform/index.js +58 -53
  39. package/src/rules/prefer-token/index.js +31 -46
  40. package/src/rules/use-motion-scale/index.js +14 -1
  41. package/src/rules/use-scale/index.js +75 -102
  42. package/src/rules/validate.js +13 -4
  43. package/types/__checks__/consumer.ts +20 -1
  44. package/types/__checks__/eslint-config.ts +8 -0
  45. package/types/__checks__/shipped-configs.ts +96 -0
  46. package/types/audit.d.ts +103 -16
  47. package/types/index.d.ts +15 -0
  48. package/types/shared.d.ts +126 -20
@@ -3,6 +3,7 @@
3
3
  const fs = require('node:fs');
4
4
  const path = require('node:path');
5
5
 
6
+ const { readJsonFile } = require('./json');
6
7
  const { parseLengthToken, toPx } = require('./length');
7
8
  const { buildEffectiveTokenMap } = require('./token-map');
8
9
  const {
@@ -18,7 +19,14 @@ const { getScalePreset } = require('../presets/scales');
18
19
  // Matches the audit default so lint and audit agree on what a spacing token is.
19
20
  const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing|spacer)(-|$)';
20
21
  // Tailwind v4 defines one base (`--spacing: 0.25rem`) and derives utilities by multiplying it.
21
- const TAILWIND_BASE_TOKENS = new Set(['--spacing', '--space']);
22
+ // A bare `--space` is not Tailwind's; it is one token like any other (issue #293).
23
+ const TAILWIND_BASE_TOKENS = new Set(['--spacing']);
24
+ // A bare `--space` is a base only when the other spacing tokens do not form a
25
+ // scale on their own. Discourse declares `--space: 0.25rem` and writes every
26
+ // step as `calc(var(--space) * N)`, so its scale is the multiples; a ladder of
27
+ // plain lengths (`--space-s`, `--space-m`) next to `--space` is the scale, and
28
+ // `--space` is one more step on it (issue #293).
29
+ const CONDITIONAL_BASE_TOKENS = new Set(['--space']);
22
30
  const TAILWIND_SPACING_MULTIPLIERS = [
23
31
  0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96,
24
32
  ];
@@ -38,7 +46,7 @@ const TOKEN_PACKAGES = require('./token-packages.json').packages;
38
46
  */
39
47
  function readDirectDependencies(dir) {
40
48
  try {
41
- const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
49
+ const pkg = readJsonFile(path.join(dir, 'package.json'));
42
50
  return new Set([
43
51
  ...Object.keys(pkg.dependencies || {}),
44
52
  ...Object.keys(pkg.devDependencies || {}),
@@ -171,13 +179,38 @@ function parseSourcesCached(sources, baseFontSize) {
171
179
  return warnings.length > 0 ? { ...parsed, warnings: [...warnings, ...parsed.warnings] } : parsed;
172
180
  }
173
181
 
182
+ /**
183
+ * Token sources read for the spacing names and, when a rule sets its own
184
+ * `tokenPattern` (`^--space-|^--radius-`), for that pattern too, on top of the
185
+ * spacing names, unless a source sets its own. Fixes and scale inference read
186
+ * the same tokens through this (issue #296).
187
+ */
188
+ function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
189
+ const plain = parseSourcesCached(sources, baseFontSize);
190
+ if (!tokenPattern || !plain) {
191
+ return plain;
192
+ }
193
+ const withPattern = parseSourcesCached(
194
+ sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source })),
195
+ baseFontSize,
196
+ );
197
+ const definitions = new Map(plain.definitions);
198
+ for (const [token, definition] of withPattern ? withPattern.definitions : []) {
199
+ if (!definitions.has(token)) {
200
+ definitions.set(token, definition);
201
+ }
202
+ }
203
+ const warnings = Array.from(new Set([...plain.warnings, ...(withPattern ? withPattern.warnings : [])]));
204
+ return { definitions, sources: plain.sources, warnings };
205
+ }
206
+
174
207
  /**
175
208
  * The scale a list of token sources defines, or null. Warnings from sources
176
209
  * that are missing or do not parse go into `warnings` either way, so a
177
210
  * fallback can say which source failed (issue #270).
178
211
  */
179
- function scaleFromSources(sources, baseFontSize, warnings = []) {
180
- const parsed = parseSourcesCached(sources, baseFontSize);
212
+ function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null) {
213
+ const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
181
214
  if (!parsed) {
182
215
  return null;
183
216
  }
@@ -203,16 +236,10 @@ function scaleFromSources(sources, baseFontSize, warnings = []) {
203
236
  function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenPattern = null, tokenRegex }) {
204
237
  const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
205
238
  const sources = [...scaleSources, ...rcTokenSources(process.cwd()).sources, ...discoverTokenPackages(process.cwd())];
206
- // A rule's own tokenPattern (`^--space-|^--radius-`) also applies to the
207
- // files it reads, on top of the spacing names, unless a source sets its own.
208
- const withPattern = tokenPattern
209
- ? sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source }))
210
- : [];
211
- for (const parsed of [parseSourcesCached(sources, baseFontSize), parseSourcesCached(withPattern, baseFontSize)]) {
212
- for (const [token, definition] of parsed ? parsed.definitions : []) {
213
- if (!definitions.has(token)) {
214
- definitions.set(token, definition);
215
- }
239
+ const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
240
+ for (const [token, definition] of parsed ? parsed.definitions : []) {
241
+ if (!definitions.has(token)) {
242
+ definitions.set(token, definition);
216
243
  }
217
244
  }
218
245
  return definitions;
@@ -252,17 +279,36 @@ function scaleFromDefinitions(definitions, baseFontSize = 16) {
252
279
  function scaleFromAllDefinitions(definitions, baseFontSize) {
253
280
  const keys = [];
254
281
  const baseKeys = [];
282
+ const conditionalKeys = [];
255
283
  for (const definition of definitions.values()) {
256
284
  if (TAILWIND_BASE_TOKENS.has(definition.token)) {
257
285
  baseKeys.push(...definition.normalizedValues);
258
286
  continue;
259
287
  }
288
+ if (CONDITIONAL_BASE_TOKENS.has(definition.token)) {
289
+ conditionalKeys.push(...definition.normalizedValues);
290
+ continue;
291
+ }
260
292
  keys.push(...definition.normalizedValues);
261
293
  }
262
- const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
294
+ const scale = scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys });
263
295
  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
264
296
  }
265
297
 
298
+ /**
299
+ * The scale from plain token values, expanded by a base multiplier where one
300
+ * applies: `--spacing` always, a bare `--space` only when the plain values do
301
+ * not already form a scale (see CONDITIONAL_BASE_TOKENS).
302
+ */
303
+ function scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys }) {
304
+ const plain = pxValuesFromKeys(keys, baseFontSize);
305
+ if (baseKeys.length > 0 || plain.length >= MIN_INFERRED_SCALE_LENGTH || conditionalKeys.length === 0) {
306
+ const withConditional = conditionalKeys.length > 0 ? pxValuesFromKeys([...keys, ...conditionalKeys], baseFontSize) : plain;
307
+ return expandTailwindBase(withConditional, baseKeys, baseFontSize);
308
+ }
309
+ return expandTailwindBase(plain, conditionalKeys, baseFontSize);
310
+ }
311
+
266
312
  /** The scope of a declaration node: the AST-side twin of customPropertyDeclarations. */
267
313
  function scopeOfNode(decl) {
268
314
  for (let node = decl.parent; node; node = node.parent) {
@@ -302,8 +348,8 @@ function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
302
348
  }
303
349
 
304
350
  /**
305
- * Merge Tailwind-style base multiples into a scale when a bare --spacing/--space
306
- * base is defined. Only the first base found is expanded: a project that ships
351
+ * Merge Tailwind-style base multiples into a scale when a bare --spacing base
352
+ * is defined. Only the first base found is expanded: a project that ships
307
353
  * several theme files with different bases (shadcn/ui) has one active base at a
308
354
  * time, and a union of ladders is a scale nobody designed (issue #89).
309
355
  */
@@ -354,7 +400,7 @@ function rcTokenSourcesUncached(rcPath) {
354
400
 
355
401
  let config;
356
402
  try {
357
- config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
403
+ config = readJsonFile(rcPath);
358
404
  } catch (err) {
359
405
  return { sources: [], warnings: [`${RC_FILE} could not be read: ${err.message}`] };
360
406
  }
@@ -400,39 +446,47 @@ function sassTokensFromRoot(root) {
400
446
  function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
401
447
  const keys = [...extraKeys];
402
448
  const baseKeys = [];
449
+ const conditionalKeys = [];
403
450
  for (const [key, reference] of Object.entries(map)) {
404
451
  const name = String(reference).match(/^var\((--[\w-]+)\)$/);
405
452
  if (name && TAILWIND_BASE_TOKENS.has(name[1])) {
406
453
  baseKeys.push(key);
454
+ } else if (name && CONDITIONAL_BASE_TOKENS.has(name[1])) {
455
+ conditionalKeys.push(key);
407
456
  } else {
408
457
  keys.push(key);
409
458
  }
410
459
  }
411
- const scale = expandTailwindBase(pxValuesFromKeys(keys, baseFontSize), baseKeys, baseFontSize);
460
+ const scale = scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys });
412
461
  return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
413
462
  }
414
463
 
415
464
  /**
416
465
  * Resolve `scale: "auto"`. First matching source wins; sources are not merged so
417
- * the provenance is a single file list or the stylesheet.
466
+ * the provenance is a single file list or the stylesheet. The order, which
467
+ * docs/rules/use-scale.md documents: `scaleSources`, `.rhythmguardrc.json`
468
+ * token sources, the linted stylesheet, `tailwindConfigPath`, installed token
469
+ * packages, the fallback preset. `sourceTokenPattern` is the rule's own
470
+ * explicit `tokenPattern`, applied to the token files as fixes apply it.
418
471
  */
419
472
  function resolveAutoScale({
420
473
  baseFontSize = 16,
421
474
  root,
422
475
  scaleSources = [],
476
+ sourceTokenPattern = null,
423
477
  tailwindConfigPath = null,
424
478
  tokenPattern = DEFAULT_AUTO_TOKEN_PATTERN,
425
479
  } = {}) {
426
480
  // Warnings from every source tried, for the fallback note when none yields a scale.
427
481
  const warnings = [];
428
- const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings);
482
+ const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern);
429
483
  if (fromOption) {
430
484
  return { source: 'scaleSources', ...fromOption };
431
485
  }
432
486
 
433
487
  const rc = rcTokenSources(process.cwd());
434
488
  warnings.push(...rc.warnings);
435
- const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings);
489
+ const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern);
436
490
  if (fromRc) {
437
491
  return { source: 'rhythmguardrc', ...fromRc };
438
492
  }
@@ -473,7 +527,7 @@ function resolveAutoScale({
473
527
  }
474
528
  }
475
529
 
476
- const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings);
530
+ const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings, sourceTokenPattern);
477
531
  if (fromPackages) {
478
532
  return { source: 'token-package', ...fromPackages };
479
533
  }
@@ -546,6 +600,7 @@ function withResolvedScale(options, root) {
546
600
  baseFontSize: options.baseFontSize,
547
601
  root,
548
602
  scaleSources: options.scaleSources,
603
+ sourceTokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
549
604
  tailwindConfigPath: options.tailwindConfigPath,
550
605
  tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
551
606
  });
@@ -172,8 +172,9 @@ function analyzeClassToken(token, options, scalePx) {
172
172
  return null;
173
173
  }
174
174
 
175
- // `-m-[16px]` and `m-[-16px]` are both negative margins (#241).
176
- const negative = match.groups.utility.startsWith('-') || parsedLength.number < 0;
175
+ // `-m-[16px]` and `m-[-16px]` are both negative margins (#241); in
176
+ // `-m-[-16px]` the two signs cancel and Tailwind writes a positive margin (#277).
177
+ const negative = match.groups.utility.startsWith('-') !== parsedLength.number < 0;
177
178
 
178
179
  if (!options.allowNegative && negative) {
179
180
  return {
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ const { readJsonFile } = require('./json');
3
4
  const { parseTokenValueLength } = require('./token-sources');
4
5
 
5
6
  const { spawnSync } = require('node:child_process');
@@ -140,7 +141,7 @@ function mergeTokenMapFromFile({
140
141
 
141
142
  let parsed;
142
143
  try {
143
- parsed = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
144
+ parsed = readJsonFile(resolvedPath);
144
145
  } catch {
145
146
  return currentMap;
146
147
  }
@@ -3,6 +3,7 @@
3
3
  const fs = require('node:fs');
4
4
  const path = require('node:path');
5
5
 
6
+ const { stripBom } = require('./json');
6
7
  const {
7
8
  formatLength,
8
9
  parseLengthToken,
@@ -86,15 +87,41 @@ function createTokenKindMatcher(kind) {
86
87
  return (token) => pattern.test(token);
87
88
  }
88
89
 
90
+ /**
91
+ * Why a source that parsed gave nothing: what was looked for, and for spacing
92
+ * the naming rule a design-tool export most often misses (issue #163).
93
+ */
94
+ function emptySourceWarning(source, format, tokenKind) {
95
+ const prefix = `Token source ${source.displayPath} (${format}) yielded no`;
96
+ if (source.tokenPattern) {
97
+ return `${prefix} tokens matching tokenPattern "${source.tokenPattern}".`;
98
+ }
99
+ if (tokenKind === 'all') {
100
+ return `${prefix} tokens.`;
101
+ }
102
+ if (tokenKind === 'spacing') {
103
+ return `${prefix} spacing tokens; spacing tokens are read by name (space, spacing or spacer), so set a tokenPattern on this source if its tokens are named otherwise.`;
104
+ }
105
+ return `${prefix} ${tokenKind} tokens.`;
106
+ }
107
+
108
+ /**
109
+ * Read token sources into definitions, with one report per source. With
110
+ * `warnWhenEmpty`, a source that parses but yields no token of the kind read
111
+ * gets a warning too; the audit and `rhythmguard doctor` ask for that for the
112
+ * token sources a project configures.
113
+ */
89
114
  function parseTokenSources({
90
115
  baseFontSize = 16,
91
116
  sources = [],
92
117
  tokenKind = 'spacing',
118
+ warnWhenEmpty = false,
93
119
  } = {}) {
94
120
  const definitions = new Map();
95
121
  const sourceReports = [];
96
122
  const warnings = [];
97
123
  const matchesKind = createTokenKindMatcher(tokenKind);
124
+ const kind = normalizeTokenKind(tokenKind);
98
125
 
99
126
  for (const source of sources) {
100
127
  const normalizedSource = normalizeTokenSource(source);
@@ -116,7 +143,7 @@ function parseTokenSources({
116
143
 
117
144
  let text;
118
145
  try {
119
- text = fs.readFileSync(normalizedSource.resolvedPath, 'utf8');
146
+ text = stripBom(fs.readFileSync(normalizedSource.resolvedPath, 'utf8'));
120
147
  } catch (err) {
121
148
  const warning = `Unable to read token source ${normalizedSource.displayPath}: ${err.message}`;
122
149
  sourceReport.warnings.push(warning);
@@ -155,6 +182,12 @@ function parseTokenSources({
155
182
  warnings.push(warning);
156
183
  }
157
184
 
185
+ if (warnWhenEmpty && tokens.length === 0) {
186
+ const warning = emptySourceWarning(normalizedSource, sourceReport.format, kind);
187
+ sourceReport.warnings.push(warning);
188
+ warnings.push(warning);
189
+ }
190
+
158
191
  for (const token of tokens) {
159
192
  addDefinition(definitions, {
160
193
  baseFontSize,
@@ -971,7 +1004,7 @@ function collectJsonTokens(parsed, matchesKind, onSkip = () => {}) {
971
1004
  return tokens;
972
1005
  }
973
1006
 
974
- function walkJsonTokenGroup(group, segments, tokens, context) {
1007
+ function walkJsonTokenGroup(group, segments, tokens, context, inheritedType = null) {
975
1008
  const { matchesKind, onSkip } = context;
976
1009
  for (const [key, value] of Object.entries(group)) {
977
1010
  if (isMetadataKey(key)) {
@@ -990,7 +1023,9 @@ function walkJsonTokenGroup(group, segments, tokens, context) {
990
1023
  continue;
991
1024
  }
992
1025
 
993
- const leaf = leafTokenValue(value, context.root);
1026
+ // DTCG `$type` applies to the node and, on a group, to every token below it.
1027
+ const type = typeof value.$type === 'string' ? value.$type : inheritedType;
1028
+ const leaf = leafTokenValue(value, context.root, type);
994
1029
  if (leaf !== null) {
995
1030
  const token = key.startsWith('--')
996
1031
  ? key
@@ -1005,7 +1040,7 @@ function walkJsonTokenGroup(group, segments, tokens, context) {
1005
1040
  continue;
1006
1041
  }
1007
1042
 
1008
- walkJsonTokenGroup(value, [...segments, key], tokens, context);
1043
+ walkJsonTokenGroup(value, [...segments, key], tokens, context, type);
1009
1044
  }
1010
1045
  }
1011
1046
 
@@ -1045,6 +1080,9 @@ function tokenFromPrimitive(key, value, segments) {
1045
1080
  const DTCG_DIMENSION_UNITS = new Set(['px', 'rem']);
1046
1081
  const JSON_REFERENCE = /^\{([^{}]+)\}$/;
1047
1082
  const MAX_JSON_REFERENCE_DEPTH = 32;
1083
+ // Raw values that are not plain JSON: a `$ref` token and a malformed dimension.
1084
+ const JSON_POINTER_REF = Symbol('json pointer reference');
1085
+ const INVALID_DIMENSION = Symbol('invalid dimension');
1048
1086
 
1049
1087
  function isDimensionObject(value) {
1050
1088
  return isPlainObject(value)
@@ -1052,9 +1090,30 @@ function isDimensionObject(value) {
1052
1090
  && typeof value.unit === 'string';
1053
1091
  }
1054
1092
 
1093
+ /** `{ "value": "16", "unit": "px" }` or `{ "unit": "px" }`: shaped like a dimension, not one. */
1094
+ function isMalformedDimension(value) {
1095
+ return isPlainObject(value)
1096
+ && !isDimensionObject(value)
1097
+ && (Object.prototype.hasOwnProperty.call(value, 'value') || Object.prototype.hasOwnProperty.call(value, 'unit'));
1098
+ }
1099
+
1100
+ /**
1101
+ * A DTCG 2025.10 `$ref` token: a JSON Pointer into the same file
1102
+ * (`"$ref": "#/base/$value/fontSize"`) in place of `$value`. Only a node with
1103
+ * nothing but `$` keys is one, so a group that happens to carry `$ref` is
1104
+ * still walked as a group.
1105
+ */
1106
+ function jsonPointerOf(node) {
1107
+ if (typeof node.$ref !== 'string' || Object.prototype.hasOwnProperty.call(node, '$value')) {
1108
+ return null;
1109
+ }
1110
+ return Object.keys(node).every((key) => key.startsWith('$')) ? node.$ref : null;
1111
+ }
1112
+
1055
1113
  /**
1056
- * The raw value a token node holds: `$value` (DTCG, any shape) or a string or
1057
- * number `value` (Style Dictionary). Undefined when the node is a group.
1114
+ * The raw value a token node holds: `$value` (DTCG, any shape), a `$ref`
1115
+ * pointer, or a string or number `value` (Style Dictionary). Undefined when
1116
+ * the node is a group or holds something other than a length (a color).
1058
1117
  */
1059
1118
  function rawTokenValue(node) {
1060
1119
  if (!isPlainObject(node)) {
@@ -1065,7 +1124,11 @@ function rawTokenValue(node) {
1065
1124
  if (typeof raw === 'string' || typeof raw === 'number' || isDimensionObject(raw)) {
1066
1125
  return raw;
1067
1126
  }
1068
- return undefined;
1127
+ return isMalformedDimension(raw) ? { [INVALID_DIMENSION]: true } : undefined;
1128
+ }
1129
+ const pointer = jsonPointerOf(node);
1130
+ if (pointer !== null) {
1131
+ return { [JSON_POINTER_REF]: pointer };
1069
1132
  }
1070
1133
  if (isDimensionObject(node)) {
1071
1134
  // `{ "value": 4, "unit": "rem" }` is one dimension, not a number with metadata.
@@ -1092,16 +1155,82 @@ function lookupJsonReference(root, reference) {
1092
1155
  return isPlainObject(node) ? rawTokenValue(node) : node;
1093
1156
  }
1094
1157
 
1158
+ /** The value a same-file JSON Pointer (`#/a/b/0`, RFC 6901) names, or undefined. */
1159
+ function lookupJsonPointer(root, pointer) {
1160
+ if (pointer === '#') {
1161
+ return root;
1162
+ }
1163
+ if (!pointer.startsWith('#/')) {
1164
+ return undefined;
1165
+ }
1166
+ let node = root;
1167
+ for (const encoded of pointer.slice(2).split('/')) {
1168
+ let segment;
1169
+ try {
1170
+ segment = decodeURIComponent(encoded).replace(/~1/g, '/').replace(/~0/g, '~');
1171
+ } catch {
1172
+ return undefined;
1173
+ }
1174
+ if (Array.isArray(node)) {
1175
+ if (!/^(?:0|[1-9]\d*)$/.test(segment) || Number(segment) >= node.length) {
1176
+ return undefined;
1177
+ }
1178
+ node = node[Number(segment)];
1179
+ } else if (isPlainObject(node) && Object.prototype.hasOwnProperty.call(node, segment)) {
1180
+ node = node[segment];
1181
+ } else {
1182
+ return undefined;
1183
+ }
1184
+ }
1185
+ return node;
1186
+ }
1187
+
1188
+ /**
1189
+ * A `$ref` token's value. The pointer names a value inside the file, usually a
1190
+ * `$value` or a part of one. A dimension object or a string is read as any
1191
+ * `$value` is; a number is read too, except for a `dimension` token, which
1192
+ * needs the whole `{ value, unit }` object. A pointer to a color or a
1193
+ * composite is not a length and is left out quietly; one that names nothing is
1194
+ * skipped with a warning.
1195
+ */
1196
+ function resolveJsonPointer(pointer, root, stack, type) {
1197
+ if (stack.has(pointer)) {
1198
+ return { skipped: `reference cycle through "${pointer}"`, value: null };
1199
+ }
1200
+ const target = lookupJsonPointer(root, pointer);
1201
+ if (target === undefined) {
1202
+ return { skipped: `reference "${pointer}" does not resolve`, value: null };
1203
+ }
1204
+ if (typeof target === 'number' && type === 'dimension') {
1205
+ return { skipped: `reference "${pointer}" is a number, not a dimension`, value: null };
1206
+ }
1207
+ if (typeof target === 'string' || typeof target === 'number' || isDimensionObject(target) || isMalformedDimension(target)) {
1208
+ stack.add(pointer);
1209
+ const resolved = resolveJsonValue(isMalformedDimension(target) ? { [INVALID_DIMENSION]: true } : target, root, stack, type);
1210
+ stack.delete(pointer);
1211
+ return resolved;
1212
+ }
1213
+ return { value: null };
1214
+ }
1215
+
1095
1216
  /**
1096
1217
  * A raw token value as a string: a number as written, a dimension object as
1097
- * `4px` or `0.75rem`, a whole-value reference followed through the file. A
1098
- * reference that cannot be followed (a missing target, a cycle) keeps its text,
1099
- * as before, and reads as a non-length; a dimension in another unit is skipped.
1218
+ * `4px` or `0.75rem`, a reference (`{spacing.2}` or a `$ref` pointer)
1219
+ * followed through the file. A `{}` reference that cannot be followed (a
1220
+ * missing target, a cycle) keeps its text, as before, and reads as a
1221
+ * non-length; a `$ref` that cannot be followed, a dimension in another unit
1222
+ * and a malformed dimension are skipped.
1100
1223
  */
1101
- function resolveJsonValue(raw, root, stack = new Set()) {
1224
+ function resolveJsonValue(raw, root, stack = new Set(), type = null) {
1102
1225
  if (typeof raw === 'number') {
1103
1226
  return { value: String(raw) };
1104
1227
  }
1228
+ if (isPlainObject(raw) && raw[INVALID_DIMENSION]) {
1229
+ return { skipped: 'dimension needs a number "value" and a "unit"', value: null };
1230
+ }
1231
+ if (isPlainObject(raw) && typeof raw[JSON_POINTER_REF] === 'string') {
1232
+ return resolveJsonPointer(raw[JSON_POINTER_REF], root, stack, type);
1233
+ }
1105
1234
  if (isDimensionObject(raw)) {
1106
1235
  const unit = raw.unit.trim().toLowerCase();
1107
1236
  if (!Number.isFinite(raw.value) || !DTCG_DIMENSION_UNITS.has(unit)) {
@@ -1125,7 +1254,7 @@ function resolveJsonValue(raw, root, stack = new Set()) {
1125
1254
  return { value: raw };
1126
1255
  }
1127
1256
  stack.add(target);
1128
- const resolved = resolveJsonValue(next, root, stack);
1257
+ const resolved = resolveJsonValue(next, root, stack, type);
1129
1258
  stack.delete(target);
1130
1259
  if (resolved.value === null && !resolved.skipped) {
1131
1260
  return { value: raw };
@@ -1134,12 +1263,12 @@ function resolveJsonValue(raw, root, stack = new Set()) {
1134
1263
  }
1135
1264
 
1136
1265
  /** The value of a token node, resolved; null when the node is a group, not a token. */
1137
- function leafTokenValue(node, root = node) {
1266
+ function leafTokenValue(node, root = node, type = null) {
1138
1267
  const raw = rawTokenValue(node);
1139
1268
  if (raw === undefined) {
1140
1269
  return null;
1141
1270
  }
1142
- return resolveJsonValue(raw, root);
1271
+ return resolveJsonValue(raw, root, new Set(), type);
1143
1272
  }
1144
1273
 
1145
1274
  function isMetadataKey(key) {
@@ -3,17 +3,23 @@
3
3
  const tailwindClassUseScale = require('./rules/tailwind-class-use-scale');
4
4
  const tailwindClassUseMotionScale = require('./rules/tailwind-class-use-motion-scale');
5
5
 
6
- module.exports = {
6
+ const plugin = {
7
7
  rules: {
8
8
  'tailwind-class-use-scale': tailwindClassUseScale,
9
9
  'tailwind-class-use-motion-scale': tailwindClassUseMotionScale,
10
10
  },
11
- configs: {
12
- recommended: {
13
- rules: {
14
- 'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
15
- 'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
16
- },
17
- },
11
+ configs: {},
12
+ };
13
+
14
+ // A flat config that works on its own (`export default [rhythmguard.configs.recommended]`),
15
+ // so it registers the plugin under the prefix its rules use (#279). Spreading
16
+ // `configs.recommended.rules` into a block that registers the plugin itself still works.
17
+ plugin.configs.recommended = {
18
+ plugins: { 'rhythmguard-tailwind': plugin },
19
+ rules: {
20
+ 'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
21
+ 'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
18
22
  },
19
23
  };
24
+
25
+ module.exports = plugin;
@@ -54,6 +54,7 @@ function buildMessage(analysis, segment, lower, upper) {
54
54
 
55
55
  module.exports = {
56
56
  meta: {
57
+ type: 'suggestion',
57
58
  docs: {
58
59
  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-motion-scale.md',
59
60
  description: 'Enforce duration scale for Tailwind arbitrary motion utilities in class strings',
@@ -34,6 +34,7 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
34
34
 
35
35
  module.exports = {
36
36
  meta: {
37
+ type: 'suggestion',
37
38
  docs: {
38
39
  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-scale.md',
39
40
  description: 'Enforce spacing scale for Tailwind arbitrary spacing utilities in class strings',