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
@@ -21,7 +21,7 @@ const {
21
21
  resolveScaleSelection,
22
22
  } = require('../presets/scales');
23
23
 
24
- const DEFAULT_SCALE = getScalePreset('rhythmic-4') || [0, 4, 8, 12, 16, 24, 32];
24
+ const { DEFAULT_SCALE } = require('../presets/default-scale');
25
25
  const VALIDATE_ALWAYS = () => true;
26
26
  const SUPPORTED_MATH_FUNCTIONS = new Set(Array.from(MATH_FUNCTIONS));
27
27
 
@@ -146,6 +146,7 @@ function parseRegexLikeString(value) {
146
146
  try {
147
147
  return new RegExp(pattern, flags);
148
148
  } catch {
149
+ // Not a valid regex: validation then rejects the entry as an unknown property.
149
150
  return null;
150
151
  }
151
152
  }
@@ -9,12 +9,15 @@ const { buildEffectiveTokenMap } = require('./token-map');
9
9
  const {
10
10
  addDefinition,
11
11
  collectScssTokens,
12
+ conditionsOfNode,
13
+ scopeOfNode,
12
14
  createTokenKindMatcher,
13
15
  parseTokenSources,
14
16
  parseTokenValueLength,
15
17
  } = require('./token-sources');
16
18
  const { normalizeTokenSourceEntry } = require('./token-source-entries');
17
19
  const { getScalePreset } = require('../presets/scales');
20
+ const { TAILWIND_SPACING_MULTIPLIERS } = require('../presets/default-scale');
18
21
 
19
22
  // Matches the audit default so lint and audit agree on what a spacing token is.
20
23
  const DEFAULT_AUTO_TOKEN_PATTERN = '(^--|-)(?<!letter-)(?<!word-)(space|spacing|spacer)(-|$)';
@@ -27,9 +30,6 @@ const TAILWIND_BASE_TOKENS = new Set(['--spacing']);
27
30
  // plain lengths (`--space-s`, `--space-m`) next to `--space` is the scale, and
28
31
  // `--space` is one more step on it (issue #293).
29
32
  const CONDITIONAL_BASE_TOKENS = new Set(['--space']);
30
- const TAILWIND_SPACING_MULTIPLIERS = [
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,
32
- ];
33
33
  const FALLBACK_PRESET = 'rhythmic-4';
34
34
  // Zero plus at least three distinct token values; a one- or two-token scale is worse than the default.
35
35
  const MIN_INFERRED_SCALE_LENGTH = 4;
@@ -53,6 +53,7 @@ function readDirectDependencies(dir) {
53
53
  ...Object.keys(pkg.peerDependencies || {}),
54
54
  ]);
55
55
  } catch {
56
+ // No package.json, or one npm could not read either: no dependencies to discover.
56
57
  return null;
57
58
  }
58
59
  }
@@ -151,11 +152,11 @@ function pxValuesFromKeys(keys, baseFontSize) {
151
152
  * do not normalise (a bad format, no path) are skipped with a warning; they
152
153
  * never throw out of a lint.
153
154
  */
154
- function parseSourcesCached(sources, baseFontSize) {
155
+ function parseSourcesCached(sources, baseFontSize, cwd = process.cwd()) {
155
156
  const normalized = [];
156
157
  const warnings = [];
157
158
  for (const entry of sources) {
158
- const { error, source } = normalizeTokenSourceEntry(entry, process.cwd());
159
+ const { error, source } = normalizeTokenSourceEntry(entry, cwd);
159
160
  if (error) {
160
161
  warnings.push(error);
161
162
  } else {
@@ -185,14 +186,15 @@ function parseSourcesCached(sources, baseFontSize) {
185
186
  * spacing names, unless a source sets its own. Fixes and scale inference read
186
187
  * the same tokens through this (issue #296).
187
188
  */
188
- function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
189
- const plain = parseSourcesCached(sources, baseFontSize);
189
+ function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null, cwd = process.cwd()) {
190
+ const plain = parseSourcesCached(sources, baseFontSize, cwd);
190
191
  if (!tokenPattern || !plain) {
191
192
  return plain;
192
193
  }
193
194
  const withPattern = parseSourcesCached(
194
195
  sources.map((source) => (typeof source === 'string' ? { path: source, tokenPattern } : { tokenPattern, ...source })),
195
196
  baseFontSize,
197
+ cwd,
196
198
  );
197
199
  const definitions = new Map(plain.definitions);
198
200
  for (const [token, definition] of withPattern ? withPattern.definitions : []) {
@@ -209,8 +211,8 @@ function parseSourcesWithPattern(sources, baseFontSize, tokenPattern = null) {
209
211
  * that are missing or do not parse go into `warnings` either way, so a
210
212
  * fallback can say which source failed (issue #270).
211
213
  */
212
- function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null) {
213
- const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern);
214
+ function scaleFromSources(sources, baseFontSize, warnings = [], tokenPattern = null, cwd = process.cwd()) {
215
+ const parsed = parseSourcesWithPattern(sources, baseFontSize, tokenPattern, cwd);
214
216
  if (!parsed) {
215
217
  return null;
216
218
  }
@@ -309,24 +311,6 @@ function scaleWithBase({ baseFontSize, baseKeys, conditionalKeys, keys }) {
309
311
  return expandTailwindBase(plain, conditionalKeys, baseFontSize);
310
312
  }
311
313
 
312
- /** The scope of a declaration node: the AST-side twin of customPropertyDeclarations. */
313
- function scopeOfNode(decl) {
314
- for (let node = decl.parent; node; node = node.parent) {
315
- if (node.type === 'rule') {
316
- return String(node.selector).split(',').every((selector) => ROOT_SELECTOR.test(selector.trim())) ? 'root' : 'component';
317
- }
318
- if (node.type === 'atrule') {
319
- const name = String(node.name).toLowerCase();
320
- if (name === 'theme') return 'root';
321
- if (!TRANSPARENT_AT_RULES.has(name)) return 'component';
322
- }
323
- }
324
- return 'root';
325
- }
326
-
327
- const ROOT_SELECTOR = /^(?::root|html|:host|:(?:where|is)\(\s*(?::root|html)\s*\))$/i;
328
- const TRANSPARENT_AT_RULES = new Set(['media', 'supports', 'layer', 'container', 'scope', 'document']);
329
-
330
314
  /** Token definitions declared in the linted stylesheet itself: custom properties with their scope, plus Sass variables and maps. */
331
315
  function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
332
316
  const definitions = new Map();
@@ -339,7 +323,8 @@ function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
339
323
  if (!parsed || parsed.number === 0) {
340
324
  return;
341
325
  }
342
- addDefinition(definitions, { baseFontSize, file: 'stylesheet', scope: scopeOfNode(decl), source: 'stylesheet', token: decl.prop, value: decl.value });
326
+ // A component token is in scope only inside its own block (fix-02).
327
+ addDefinition(definitions, { anchor: decl.parent, baseFontSize, conditions: conditionsOfNode(decl), file: 'stylesheet', scope: scopeOfNode(decl), source: 'stylesheet', token: decl.prop, value: decl.value });
343
328
  });
344
329
  for (const sassToken of sassTokensFromRoot(root)) {
345
330
  addDefinition(definitions, { baseFontSize, file: 'stylesheet', scope: 'root', source: 'stylesheet', token: sassToken.token, value: sassToken.value });
@@ -468,9 +453,13 @@ function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
468
453
  * token sources, the linted stylesheet, `tailwindConfigPath`, installed token
469
454
  * packages, the fallback preset. `sourceTokenPattern` is the rule's own
470
455
  * explicit `tokenPattern`, applied to the token files as fixes apply it.
456
+ * `cwd` is the project directory that relative `scaleSources`, the rc file
457
+ * and installed token packages are read from; the rules leave it to default.
471
458
  */
472
459
  function resolveAutoScale({
473
460
  baseFontSize = 16,
461
+ cwd = process.cwd(),
462
+ fallbackPreset = FALLBACK_PRESET,
474
463
  root,
475
464
  scaleSources = [],
476
465
  sourceTokenPattern = null,
@@ -479,22 +468,23 @@ function resolveAutoScale({
479
468
  } = {}) {
480
469
  // Warnings from every source tried, for the fallback note when none yields a scale.
481
470
  const warnings = [];
482
- const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern);
471
+ const fromOption = scaleFromSources(scaleSources, baseFontSize, warnings, sourceTokenPattern, cwd);
483
472
  if (fromOption) {
484
- return { source: 'scaleSources', ...fromOption };
473
+ return { source: 'scaleSources', ...fromOption, warnings: [...warnings] };
485
474
  }
486
475
 
487
- const rc = rcTokenSources(process.cwd());
476
+ const rc = rcTokenSources(cwd);
488
477
  warnings.push(...rc.warnings);
489
- const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern);
478
+ const fromRc = scaleFromSources(rc.sources, baseFontSize, warnings, sourceTokenPattern, cwd);
490
479
  if (fromRc) {
491
- return { source: 'rhythmguardrc', ...fromRc };
480
+ return { source: 'rhythmguardrc', ...fromRc, warnings: [...warnings] };
492
481
  }
493
482
 
494
483
  let tokenRegex;
495
484
  try {
496
485
  tokenRegex = new RegExp(tokenPattern);
497
486
  } catch {
487
+ // createTokenRegex reports an invalid tokenPattern; inference reads the default names.
498
488
  tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN);
499
489
  }
500
490
 
@@ -504,35 +494,45 @@ function resolveAutoScale({
504
494
  if (scale) {
505
495
  const assessment = assessScale({ source: 'stylesheet', values: scale });
506
496
  if (assessment.plausible) {
507
- return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
497
+ return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [...warnings] };
508
498
  }
509
499
  rejected = { reasons: assessment.reasons, source: 'stylesheet', values: scale };
510
500
  }
511
501
  }
512
502
 
513
503
  if (tailwindConfigPath) {
514
- const tailwindMap = buildEffectiveTokenMap({
515
- options: {
516
- baseFontSize,
517
- tailwindConfigPath,
518
- tokenMap: {},
519
- tokenMapFromTailwindSpacing: true,
520
- },
521
- root,
522
- tokenRegex,
523
- });
524
- const scale = scaleFromTokenMap(tailwindMap, baseFontSize);
504
+ const scale = scaleFromTailwindConfig(tailwindConfigPath, baseFontSize, { root, tokenRegex, warnings });
525
505
  if (scale) {
526
- return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [] };
506
+ return { files: [tailwindConfigPath], scale, source: 'tailwind', tokenCount: scale.length - 1, warnings: [...warnings] };
527
507
  }
528
508
  }
529
509
 
530
- const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize, warnings, sourceTokenPattern);
510
+ const fromPackages = scaleFromSources(discoverTokenPackages(cwd), baseFontSize, warnings, sourceTokenPattern, cwd);
531
511
  if (fromPackages) {
532
- return { source: 'token-package', ...fromPackages };
512
+ return { source: 'token-package', ...fromPackages, warnings: [...warnings] };
533
513
  }
534
514
 
535
- return fallbackInference(rejected, warnings);
515
+ return fallbackInference(rejected, warnings, fallbackPreset);
516
+ }
517
+
518
+ /**
519
+ * The scale in a Tailwind v3 config's `theme.spacing` (and `extend.spacing`),
520
+ * or null. The config is loaded with `require()`, so callers pass a path only
521
+ * when the user configured one.
522
+ */
523
+ function scaleFromTailwindConfig(tailwindConfigPath, baseFontSize = 16, { root = null, tokenRegex = new RegExp(DEFAULT_AUTO_TOKEN_PATTERN), warnings = [] } = {}) {
524
+ const tailwindMap = buildEffectiveTokenMap({
525
+ options: {
526
+ baseFontSize,
527
+ tailwindConfigPath,
528
+ tokenMap: {},
529
+ tokenMapFromTailwindSpacing: true,
530
+ },
531
+ root,
532
+ tokenRegex,
533
+ warnings,
534
+ });
535
+ return scaleFromTokenMap(tailwindMap, baseFontSize);
536
536
  }
537
537
 
538
538
  const TRUSTED_SCALE_SOURCES = new Set(['scaleSources', 'rhythmguardrc', 'token-sources', 'tailwind', 'token-package', 'explicit', 'default']);
@@ -577,12 +577,18 @@ function assessScale({ files = null, source, values = [] } = {}) {
577
577
  return { plausible: reasons.length === 0, reasons };
578
578
  }
579
579
 
580
- function fallbackInference(rejected = null, warnings = []) {
580
+ /**
581
+ * The scale when no source gives one: the rule's `preset` when it sets one
582
+ * next to `scale: "auto"` (configs/tailwind falls back to the Tailwind ladder),
583
+ * else `rhythmic-4`.
584
+ */
585
+ function fallbackInference(rejected = null, warnings = [], preset = FALLBACK_PRESET) {
586
+ const name = getScalePreset(preset) ? preset : FALLBACK_PRESET;
581
587
  return {
582
588
  files: [],
583
- preset: FALLBACK_PRESET,
589
+ preset: name,
584
590
  ...(rejected ? { rejected } : {}),
585
- scale: getScalePreset(FALLBACK_PRESET),
591
+ scale: getScalePreset(name),
586
592
  source: 'fallback',
587
593
  tokenCount: 0,
588
594
  warnings,
@@ -598,6 +604,7 @@ function withResolvedScale(options, root) {
598
604
  if (options.scaleAuto) {
599
605
  const inference = resolveAutoScale({
600
606
  baseFontSize: options.baseFontSize,
607
+ fallbackPreset: options.preset || FALLBACK_PRESET,
601
608
  root,
602
609
  scaleSources: options.scaleSources,
603
610
  sourceTokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
@@ -673,14 +680,27 @@ function sourceWarningsNote(warnings) {
673
680
  return unique.map((warning) => ` ${/[.!?]$/.test(warning) ? warning : `${warning}.`}`).join('');
674
681
  }
675
682
 
683
+ /**
684
+ * The loader warnings a rule adds to its first message in a file, beyond the
685
+ * fallback note: an rc that could not be read, a token map or Tailwind config
686
+ * that could not be loaded, a token source that failed while another gave the
687
+ * scale (cq-05). Empty when nothing failed.
688
+ */
689
+ function loaderWarningsNote(warnings, inference = null) {
690
+ const fromInference = inference && inference.source !== 'fallback' ? inference.warnings || [] : [];
691
+ return sourceWarningsNote([...(warnings || []), ...fromInference]).trim();
692
+ }
693
+
676
694
  module.exports = {
677
695
  DEFAULT_AUTO_TOKEN_PATTERN,
678
696
  assessScale,
679
697
  autoScaleFallbackNote,
680
698
  collectTokenDefinitions,
699
+ loaderWarningsNote,
681
700
  discoverTokenPackages,
682
701
  inferScaleFromDefinitions,
683
702
  resolveAutoScale,
684
703
  scaleFromDefinitions,
704
+ scaleFromTailwindConfig,
685
705
  withResolvedScale,
686
706
  };
@@ -11,16 +11,20 @@ const {
11
11
  pxOnScale,
12
12
  toPx,
13
13
  } = require('./length');
14
+ const { TAILWIND_SCALE_NAME, TAILWIND_SPACING_UNIT_REM, tailwindSpacingLadder } = require('../presets/default-scale');
14
15
 
15
- // The ESLint rule's and the audit's default scale. It is not the `rhythmic-4`
16
- // preset (which continues to 40, 48, 64); unifying the defaults changes
17
- // reports, so it waits for a major (#246).
18
- const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
19
16
  const DEFAULT_UNITS = ['px', 'rem', 'em'];
20
17
  // Tailwind's numeric spacing utilities are multiples of one unit: `--spacing`
21
18
  // (0.25rem) in v4, and the same 0.25rem step in the v3 default scale. In px
22
19
  // that is a quarter of the root font size: 4px at 16px, 2.5px at 10px (#247).
23
- const SPACING_UNIT_REM = 0.25;
20
+ const SPACING_UNIT_REM = TAILWIND_SPACING_UNIT_REM;
21
+
22
+ // Utilities Tailwind has no negative form for: padding, scroll padding and
23
+ // gap (padding and gap cannot be negative in CSS). `-p-3` and `-gap-3` are
24
+ // never generated, and `p-[-13px]` writes an invalid declaration (cs-08).
25
+ // The class regex still accepts the sign on them so a finding that was
26
+ // reported keeps being reported, now without a fix.
27
+ const NO_NEGATIVE_FORM = /^(?:p[trblxy]?|gap(?:-[xy])?|scroll-p[trblxy]?)$/;
24
28
 
25
29
  const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
26
30
 
@@ -31,16 +35,22 @@ function normalizeTailwindClassOptions(option = {}) {
31
35
  option.baseFontSize > 0
32
36
  ? option.baseFontSize
33
37
  : 16;
38
+ const spacingUnit = option.spacingUnit === false
39
+ ? null
40
+ : typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
41
+ ? option.spacingUnit
42
+ : baseFontSize * SPACING_UNIT_REM;
43
+ // No `scale`: Tailwind's default ladder on the spacing unit, so a standard
44
+ // step such as p-5 (20px) is on the scale (cs-01). Before 3.20 the default
45
+ // was 0 to 32px.
46
+ const defaultScale = !Array.isArray(option.scale);
34
47
  return {
35
48
  allowHairlines: option.allowHairlines !== false,
36
49
  allowNegative: option.allowNegative !== false,
37
50
  baseFontSize,
38
- scale: Array.isArray(option.scale) ? option.scale : DEFAULT_SCALE,
39
- spacingUnit: option.spacingUnit === false
40
- ? null
41
- : typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
42
- ? option.spacingUnit
43
- : baseFontSize * SPACING_UNIT_REM,
51
+ scale: defaultScale ? tailwindSpacingLadder(spacingUnit || baseFontSize * SPACING_UNIT_REM) : option.scale,
52
+ scaleName: defaultScale ? TAILWIND_SCALE_NAME : null,
53
+ spacingUnit,
44
54
  units: Array.isArray(option.units)
45
55
  ? option.units.map((unit) => String(unit).toLowerCase())
46
56
  : DEFAULT_UNITS,
@@ -154,6 +164,9 @@ function utilityClassFor(utility, px, negative, spacingUnit) {
154
164
  return null;
155
165
  }
156
166
  const name = utility.startsWith('-') ? utility.slice(1) : utility;
167
+ if (negative && steps !== 0 && NO_NEGATIVE_FORM.test(name)) {
168
+ return null;
169
+ }
157
170
  const sign = negative && steps !== 0 ? '-' : '';
158
171
  return `${sign}${name}-${formatNumber(Math.round(quarters) / 4)}`;
159
172
  }
@@ -213,6 +226,26 @@ function analyzeClassToken(token, options, scalePx) {
213
226
  if (!nearest) {
214
227
  return null;
215
228
  }
229
+ // Past the top step the nearest step is not a fix: 64px snapped to a 32px
230
+ // top step halves the padding (cs-01). Reported, with no fix.
231
+ const beyondScale = pxValue > scalePx[scalePx.length - 1];
232
+
233
+ // `-p-[13px]`, `p-[-13px]`, `-gap-[13px]`: still reported, as before, but
234
+ // with no fix and no suggested class, since `-p-3` and `-gap-3` do not
235
+ // exist. A double negative (`-p-[-13px]`) is no better: Tailwind has no
236
+ // `-p-*` utility at all. On-scale values were never reported and are not now.
237
+ const bareUtility = match.groups.utility.replace(/^-/, '');
238
+ if (NO_NEGATIVE_FORM.test(bareUtility) && (match.groups.utility.startsWith('-') || parsedLength.number < 0)) {
239
+ return {
240
+ fixedToken: null,
241
+ nearest,
242
+ nearestUtilities: null,
243
+ parsedLength,
244
+ reason: 'no-negative-form',
245
+ rawValue: match.groups.rawValue,
246
+ utility: match.groups.utility,
247
+ };
248
+ }
216
249
 
217
250
  const signedNearest = parsedLength.number < 0
218
251
  ? -Math.abs(nearest.nearest)
@@ -235,7 +268,7 @@ function analyzeClassToken(token, options, scalePx) {
235
268
  const fixedCandidate = utilityFix || parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
236
269
 
237
270
  return {
238
- fixedToken: wrap(fixedCandidate),
271
+ fixedToken: beyondScale ? null : wrap(fixedCandidate),
239
272
  nearest,
240
273
  // The utility classes for the two nearest steps, when both are quarter
241
274
  // steps of the spacing unit; messages name these instead of px values.
@@ -276,10 +309,20 @@ function createTailwindClassAnalyzer(option = {}) {
276
309
  * The message text for an off-scale class: the two nearest utility classes
277
310
  * with their px values when the unit makes them, the px steps otherwise.
278
311
  */
279
- function offScaleClassMessage(token, analysis) {
312
+ function offScaleClassMessage(token, analysis, scaleName = null) {
313
+ const message = offScaleClassText(token, analysis);
314
+ // The ESLint rule names the scale it fell back to, so a reader knows the
315
+ // verdict is Tailwind's default ladder and not the project's tokens.
316
+ return scaleName && analysis.reason === 'off-scale' ? `${message} Scale: ${scaleName}.` : message;
317
+ }
318
+
319
+ function offScaleClassText(token, analysis) {
280
320
  if (analysis.reason === 'negative') {
281
321
  return `Unexpected Tailwind arbitrary spacing value "${token}". Negative values are disabled for this rule.`;
282
322
  }
323
+ if (analysis.reason === 'no-negative-form') {
324
+ return `Unexpected Tailwind arbitrary spacing value "${token}". Padding and gap cannot be negative, so this class has no effect.`;
325
+ }
283
326
  const lowerPx = analysis.nearest ? formatLength(analysis.nearest.lower, 'px') : 'n/a';
284
327
  const upperPx = analysis.nearest ? formatLength(analysis.nearest.upper, 'px') : 'n/a';
285
328
  if (analysis.nearestUtilities) {
@@ -2,7 +2,7 @@
2
2
 
3
3
  const { propertyKindOf } = require('./css-vocabulary');
4
4
  const { fixedLengthValue, numbersEqual, toPx } = require('./length');
5
- const { createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
5
+ const { conditionsOfNode, createTokenKindMatcher, parseTokenValueLength } = require('./token-sources');
6
6
 
7
7
  // Dedicated kinds first: a name like --radius-space-1 is a radius token.
8
8
  const TOKEN_KINDS = ['radius', 'typography', 'motion', 'size', 'spacing'].map((kind) => [kind, createTokenKindMatcher(kind)]);
@@ -70,26 +70,65 @@ function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
70
70
  for (const { px, raw, unit } of lengths || []) {
71
71
  if (px === 0) continue;
72
72
  const file = definition.files ? [...definition.files][0] : null;
73
- index.push({ file: file && file !== 'stylesheet' ? file : null, px, raw, token: definition.token, unit });
73
+ // A definition built without scopes (an older caller) counts as declared at the root.
74
+ const fixScopes = definition.fixScopes || [{ global: true }];
75
+ index.push({ file: file && file !== 'stylesheet' ? file : null, fixScopes, px, raw, token: definition.token, unit });
74
76
  }
75
77
  }
76
78
  return index;
77
79
  }
78
80
 
81
+ /** The conditions and ancestors of a declaration being fixed, computed once per declaration. */
82
+ const placeCache = new WeakMap();
83
+ function placeOf(decl) {
84
+ if (!placeCache.has(decl)) {
85
+ const ancestors = new Set();
86
+ for (let node = decl.parent; node; node = node.parent) ancestors.add(node);
87
+ placeCache.set(decl, { ancestors, conditions: new Set(conditionsOfNode(decl)) });
88
+ }
89
+ return placeCache.get(decl);
90
+ }
91
+
92
+ /**
93
+ * Whether a token is defined where a declaration sits (fix-02). A token
94
+ * declared at the root outside every conditional at-rule is defined
95
+ * everywhere. One declared at the root under `@media`, `@supports` or
96
+ * `@container` is defined only under the same conditions, and one declared in
97
+ * a component block only inside that block. Anywhere else the property would
98
+ * be invalid at computed-value time, so the token is never offered there.
99
+ * Without a declaration (`at` undefined) every token counts.
100
+ */
101
+ function tokenDefinedAt(entry, at) {
102
+ if (!at || !entry.fixScopes) {
103
+ return true;
104
+ }
105
+ return entry.fixScopes.some((scope) => {
106
+ if (scope.global) return true;
107
+ if (scope.anchor) return placeOf(at).ancestors.has(scope.anchor);
108
+ if (scope.conditions) {
109
+ const { conditions } = placeOf(at);
110
+ return scope.conditions.every((condition) => conditions.has(condition));
111
+ }
112
+ return false;
113
+ });
114
+ }
115
+
79
116
  /**
80
117
  * Every custom property that holds a length, for one property. The shared
81
118
  * resolver behind use-scale's `fixWith: "token"` and prefer-token, so the two
82
119
  * rules always know the same tokens. The px value is signed: 8 finds the
83
120
  * tokens that hold 8px, -8 the tokens that hold -8px. Same unit first; with
84
121
  * `anyUnit`, a token in another unit that holds the same px value counts when
85
- * none matches the unit. Sorted, so messages are stable.
122
+ * none matches the unit. With `at`, the declaration being fixed, only the
123
+ * tokens defined where it sits count (see tokenDefinedAt). Sorted, so
124
+ * messages are stable.
86
125
  */
87
- function tokensForLength(index, px, unit, { anyUnit = false, prop = null } = {}) {
126
+ function tokensForLength(index, px, unit, { anyUnit = false, at = null, prop = null } = {}) {
88
127
  const wanted = unit || 'px';
89
128
  const sameUnit = new Set();
90
129
  const otherUnit = new Set();
91
130
  for (const entry of index) {
92
- if (!entry.token.startsWith('--') || !numbersEqual(entry.px, px) || !tokenFitsProperty(entry.token, prop)) {
131
+ if (!entry.token.startsWith('--') || !numbersEqual(entry.px, px) || !tokenFitsProperty(entry.token, prop) || !tokenDefinedAt(entry, at)) {
93
132
  continue;
94
133
  }
95
134
  (entry.unit === wanted ? sameUnit : otherUnit).add(entry.token);
@@ -114,8 +153,8 @@ function signedTokensForLength(index, px, unit, options = {}) {
114
153
  return { negate: px < 0, tokens: tokensForLength(index, Math.abs(px), unit, options) };
115
154
  }
116
155
 
117
- function tokenForLength(index, px, unit, prop = null) {
118
- const candidates = tokensForLength(index, px, unit, { prop });
156
+ function tokenForLength(index, px, unit, prop = null, at = null) {
157
+ const candidates = tokensForLength(index, px, unit, { at, prop });
119
158
  return candidates.length === 1 ? `var(${candidates[0]})` : null;
120
159
  }
121
160
 
@@ -135,18 +174,19 @@ function negateReplacement(replacement) {
135
174
  * options ask for one and exactly one qualifies, otherwise the literal. The
136
175
  * nearest value is in px, or in the literal's unit with `unitStrategy:
137
176
  * "exact"`; tokens are indexed in px, so the lookup converts it (issue #223).
138
- * `avoidTokens` are the var() names a fallback literal falls back from; one
139
- * of them is never written, the literal is.
177
+ * `avoidTokens` are the var() names a fallback literal falls back from. A
178
+ * fallback is what renders when tokens are missing, so no token is written
179
+ * into one, the literal is (fix-02; issue #240). `at` is the declaration being
180
+ * fixed: a token not defined there is never written (see tokenDefinedAt).
140
181
  */
141
- function replacementFor(parsedLength, nearest, options, prop = null, avoidTokens = []) {
142
- if (options.fixWith === 'token' && options.tokenIndex) {
182
+ function replacementFor(parsedLength, nearest, options, prop = null, avoidTokens = [], at = null) {
183
+ if (options.fixWith === 'token' && options.tokenIndex && avoidTokens.length === 0) {
143
184
  const unit = parsedLength.unit || 'px';
144
185
  const nearestPx = options.unitStrategy === 'exact' ? toPx(Math.abs(nearest), unit, options.baseFontSize) : Math.abs(nearest);
145
186
  if (nearestPx !== null) {
146
187
  const signedPx = parsedLength.number < 0 ? -nearestPx : nearestPx;
147
- const { negate, tokens } = signedTokensForLength(options.tokenIndex, signedPx, unit, { prop });
148
- // A var() fallback never falls back to the token it is the fallback of (issue #240).
149
- if (tokens.length === 1 && !avoidTokens.includes(tokens[0])) {
188
+ const { negate, tokens } = signedTokensForLength(options.tokenIndex, signedPx, unit, { at, prop });
189
+ if (tokens.length === 1) {
150
190
  const token = `var(${tokens[0]})`;
151
191
  return negate ? negateReplacement(token) : token;
152
192
  }
@@ -173,6 +213,7 @@ module.exports = {
173
213
  negateReplacement,
174
214
  replacementFor,
175
215
  signedTokensForLength,
216
+ tokenDefinedAt,
176
217
  tokenFitsProperty,
177
218
  tokenHoldsNote,
178
219
  tokenForLength,