stylelint-plugin-rhythmguard 3.19.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 (55) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.md +3 -3
  3. package/SECURITY.md +2 -1
  4. package/agents/claude-code/SKILL.md +1 -1
  5. package/package.json +1 -1
  6. package/src/audit/args.js +30 -8
  7. package/src/audit/baseline.js +37 -3
  8. package/src/audit/codemod.js +2 -0
  9. package/src/audit/config.js +7 -0
  10. package/src/audit/contract.js +124 -14
  11. package/src/audit/next-steps.js +3 -1
  12. package/src/audit/non-authored.js +1 -0
  13. package/src/audit/render-github.js +16 -11
  14. package/src/audit/render-markdown.js +8 -2
  15. package/src/audit/render-text.js +41 -2
  16. package/src/audit/render-utils.js +14 -0
  17. package/src/audit/report.js +230 -10
  18. package/src/audit/scan/files.js +5 -0
  19. package/src/audit/scan/stylesheets.js +48 -53
  20. package/src/audit/scan/templates.js +2 -0
  21. package/src/audit/shared.js +7 -1
  22. package/src/audit/token-chains.js +1 -0
  23. package/src/cli/audit.js +2 -2
  24. package/src/cli/doctor.js +853 -237
  25. package/src/cli/first-run.js +210 -0
  26. package/src/cli/index.js +25 -1
  27. package/src/cli/index.mjs +3 -0
  28. package/src/cli/init.js +39 -11
  29. package/src/cli/quickstart.js +53 -102
  30. package/src/cli/scale.js +223 -0
  31. package/src/configs/recommended.js +3 -1
  32. package/src/configs/strict.js +3 -1
  33. package/src/configs/tailwind.js +15 -0
  34. package/src/core/decisions.js +18 -5
  35. package/src/core/fs-cache.js +1 -0
  36. package/src/core/options.js +2 -1
  37. package/src/core/scale-inference.js +72 -52
  38. package/src/core/tailwind-class-analysis.js +56 -13
  39. package/src/core/token-index.js +55 -14
  40. package/src/core/token-map.js +136 -28
  41. package/src/core/token-sources.js +461 -40
  42. package/src/core/value-nodes.js +4 -2
  43. package/src/eslint/class-context.js +330 -0
  44. package/src/eslint/literal-spans.js +5 -4
  45. package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
  46. package/src/presets/default-scale.js +42 -0
  47. package/src/presets/scales.js +6 -1
  48. package/src/rules/no-offscale-transform/index.js +17 -5
  49. package/src/rules/prefer-token/index.js +51 -15
  50. package/src/rules/use-scale/index.js +7 -4
  51. package/types/__checks__/consumer.ts +17 -0
  52. package/types/__checks__/eslint-config.ts +5 -0
  53. package/types/audit.d.ts +40 -3
  54. package/types/cli.d.ts +77 -1
  55. package/types/shared.d.ts +10 -0
@@ -0,0 +1,223 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * `rhythmguard scale`: the scale the audit would check against, where it came
5
+ * from, and the tokens that hold each step, without scanning for findings
6
+ * (ai-04). It resolves the scale through the audit's own path (flags,
7
+ * `.rhythmguardrc.json`, `--scale auto`), so the two never disagree.
8
+ */
9
+ const { OPTIONS, parseArgs, renderOptionLines } = require('../audit/args');
10
+ const { normalizeCreateAuditOptions, prepareAuditRun, tokenScaleSources } = require('../audit/report');
11
+ const { formatLength, parseLengthToken, toPx } = require('../core/length');
12
+ const { discoverTokenPackages } = require('../core/scale-inference');
13
+ const { tokenIndexFromDefinitions } = require('../core/token-index');
14
+ const { parseTokenSources } = require('../core/token-sources');
15
+
16
+ const SCALE_FLAGS = new Set([
17
+ '--format',
18
+ '--json',
19
+ '--config',
20
+ '--no-config',
21
+ '--ignore',
22
+ '--ignore-path',
23
+ '--include-non-authored',
24
+ '--token-source',
25
+ '--token-source-format',
26
+ '--scale',
27
+ '--base-font-size',
28
+ '--help',
29
+ ]);
30
+
31
+ const SCALE_OPTIONS = OPTIONS
32
+ .filter((option) => SCALE_FLAGS.has(option.flag))
33
+ .map((option) => (option.flag === '--format'
34
+ ? { ...option, value: '<text|json>', help: 'Output format (default: text)' }
35
+ : option));
36
+
37
+ const SCALE_FORMATS = new Set(['text', 'json']);
38
+
39
+ const HELP = [
40
+ 'Usage: rhythmguard scale [dir] [options]',
41
+ '',
42
+ 'Print the spacing scale `rhythmguard audit` would check <dir> against (default: .),',
43
+ 'where it came from, and the tokens that hold each step. Resolved as the audit does:',
44
+ '--scale, then .rhythmguardrc.json, then the built-in default; --scale auto infers it',
45
+ 'from token sources, then scanned stylesheets, then installed token packages.',
46
+ 'Exits 2 when a configured token source does not exist, as the audit does.',
47
+ '',
48
+ 'Options:',
49
+ ...renderOptionLines(SCALE_OPTIONS),
50
+ '',
51
+ 'Examples:',
52
+ ' npx rhythmguard scale',
53
+ ' npx rhythmguard scale ./src --scale auto --format json',
54
+ ' npx rhythmguard scale --token-source ./tokens/tokens.json --scale auto',
55
+ '',
56
+ ].join('\n');
57
+
58
+ const SOURCE_NOTES = Object.freeze({
59
+ default: 'the built-in default; pass --scale auto to infer one from your tokens',
60
+ explicit: 'set by --scale, audit.scale or audit.scales.spacing',
61
+ fallback: 'no tokens found, so the built-in default',
62
+ 'scanned-css': 'spacing custom properties and Sass tokens in the scanned stylesheets',
63
+ tailwind: 'the configured Tailwind config',
64
+ 'token-package': 'an installed design-token package',
65
+ 'token-sources': 'the configured token sources',
66
+ });
67
+
68
+ /** The px value of a scale entry (a number is px; a string is a length), or null. */
69
+ function entryPx(entry, baseFontSize) {
70
+ if (typeof entry === 'number') {
71
+ return entry;
72
+ }
73
+ const parsed = parseLengthToken(String(entry));
74
+ return parsed ? toPx(parsed.number, parsed.unit || 'px', baseFontSize) : null;
75
+ }
76
+
77
+ /**
78
+ * The tokens that hold each step: from the token sources, the stylesheets
79
+ * that declare tokens, and installed token packages, the places prefer-token
80
+ * reads in an audit. Only tokens defined everywhere count: one declared in a
81
+ * component block or under a media query does not stand for a step.
82
+ */
83
+ function tokensByStep(run, parsed) {
84
+ const entries = tokenScaleSources({
85
+ baseFontSize: parsed.baseFontSize,
86
+ cssFiles: run.cssFiles,
87
+ isNonAuthored: run.isNonAuthored,
88
+ readSource: run.readSource,
89
+ tokenSources: parsed.tokenSources,
90
+ });
91
+ const definitions = parseTokenSources({
92
+ baseFontSize: parsed.baseFontSize,
93
+ sources: [...entries, ...discoverTokenPackages(process.cwd())],
94
+ tokenKind: 'spacing',
95
+ }).definitions;
96
+ const index = tokenIndexFromDefinitions(definitions, parsed.baseFontSize)
97
+ .filter((entry) => entry.token.startsWith('--') && entry.fixScopes.some((scope) => scope.global));
98
+
99
+ return run.scale.values.map((value) => {
100
+ const px = entryPx(value, parsed.baseFontSize);
101
+ const seen = new Set();
102
+ const tokens = [];
103
+ for (const entry of index) {
104
+ if (px === null || Math.abs(entry.px - px) > 1e-6 || seen.has(entry.token)) {
105
+ continue;
106
+ }
107
+ seen.add(entry.token);
108
+ tokens.push({ file: entry.file, token: entry.token, value: entry.raw });
109
+ }
110
+ tokens.sort((a, b) => a.token.localeCompare(b.token, 'en', { numeric: true }));
111
+ return { px, tokens, value };
112
+ });
113
+ }
114
+
115
+ /** The scale report: what `--format json` prints. */
116
+ function resolveScaleReport(parsedArgs) {
117
+ const parsed = normalizeCreateAuditOptions({ ...parsedArgs, dir: parsedArgs.dir || '.' });
118
+ const run = prepareAuditRun(parsed);
119
+ const { scale } = run;
120
+ return {
121
+ baseFontSize: parsed.baseFontSize,
122
+ command: {
123
+ config: parsed.config,
124
+ directory: parsed.dir,
125
+ },
126
+ scale: {
127
+ classStrings: scale.classStrings || null,
128
+ files: scale.files,
129
+ rejected: scale.rejected || null,
130
+ source: scale.source,
131
+ tokenCount: scale.tokenCount,
132
+ values: scale.values,
133
+ },
134
+ schemaVersion: '1.0',
135
+ steps: tokensByStep(run, parsed),
136
+ warnings: run.spacingSourceResult.warnings,
137
+ };
138
+ }
139
+
140
+ function renderScaleText(report) {
141
+ const { scale } = report;
142
+ const files = scale.files.length > 0 ? ` (${scale.files.join(', ')})` : '';
143
+ const lines = [
144
+ '',
145
+ ' Rhythmguard scale',
146
+ '',
147
+ ` Scale ${scale.values.join(', ')}`,
148
+ ` Source ${scale.source}${files}: ${SOURCE_NOTES[scale.source] || scale.source}`,
149
+ ];
150
+ if (scale.tokenCount > 0) {
151
+ lines.push(` Tokens read ${scale.tokenCount}`);
152
+ }
153
+ if (scale.rejected) {
154
+ lines.push(` Rejected ${scale.rejected.source} (${scale.rejected.values.join(', ')}): ${scale.rejected.reasons.join(', ')}`);
155
+ }
156
+ if (scale.classStrings) {
157
+ lines.push(` Class strings ${scale.classStrings.name} (${scale.classStrings.values.join(', ')})`);
158
+ }
159
+ lines.push(` Config ${report.command.config ? report.command.config.file : 'none'}`);
160
+ lines.push('');
161
+ lines.push(' Steps');
162
+ for (const step of report.steps) {
163
+ const label = typeof step.value === 'number' ? formatLength(step.value, 'px') : String(step.value);
164
+ const tokens = step.tokens.length > 0
165
+ ? step.tokens.map((entry) => `var(${entry.token})${entry.file ? ` ${entry.file}` : ''}`).join(', ')
166
+ : '';
167
+ lines.push(` ${label.padEnd(10)}${tokens}`.trimEnd());
168
+ }
169
+ if (report.warnings.length > 0) {
170
+ lines.push('');
171
+ for (const warning of report.warnings) {
172
+ lines.push(` Warning: ${warning}`);
173
+ }
174
+ }
175
+ lines.push('');
176
+ return `${lines.join('\n')}\n`;
177
+ }
178
+
179
+ function run(argv = process.argv.slice(3)) {
180
+ let parsed;
181
+ try {
182
+ parsed = parseArgs(argv, SCALE_OPTIONS);
183
+ if (!SCALE_FORMATS.has(parsed.format)) {
184
+ throw new Error(`Invalid format "${parsed.format}". Expected text or json.`);
185
+ }
186
+ } catch (err) {
187
+ process.stderr.write(`${err.message}\n\n${HELP}`);
188
+ process.exit(1);
189
+ }
190
+
191
+ if (parsed.help) {
192
+ process.stdout.write(HELP);
193
+ return;
194
+ }
195
+
196
+ let report;
197
+ try {
198
+ report = resolveScaleReport(parsed);
199
+ } catch (err) {
200
+ process.stderr.write(`${err.message}\n`);
201
+ process.exit(1);
202
+ }
203
+
204
+ process.stdout.write(parsed.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : renderScaleText(report));
205
+
206
+ const missing = report.warnings.filter((warning) => warning.startsWith('Token source not found:'));
207
+ if (missing.length > 0) {
208
+ process.stderr.write(`${missing.join('\n')}\nA configured token source does not exist, so the scale above is not the one configured. Fix the path in --token-source or audit.tokenSources.\n`);
209
+ process.exitCode = 2;
210
+ }
211
+ }
212
+
213
+ module.exports = {
214
+ HELP,
215
+ SCALE_OPTIONS,
216
+ renderScaleText,
217
+ resolveScaleReport,
218
+ run,
219
+ };
220
+
221
+ if (require.main === module) {
222
+ run();
223
+ }
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { DEFAULT_SCALE } = require('../presets/default-scale');
4
+
3
5
  /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
4
6
  module.exports = {
5
7
  plugins: ['stylelint-plugin-rhythmguard'],
@@ -7,7 +9,7 @@ module.exports = {
7
9
  'rhythmguard/use-scale': [
8
10
  true,
9
11
  {
10
- scale: [0, 4, 8, 12, 16, 24, 32, 40, 48, 64],
12
+ scale: [...DEFAULT_SCALE],
11
13
  },
12
14
  ],
13
15
  },
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { DEFAULT_SCALE } = require('../presets/default-scale');
4
+
3
5
  /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
4
6
  module.exports = {
5
7
  plugins: ['stylelint-plugin-rhythmguard'],
@@ -19,7 +21,7 @@ module.exports = {
19
21
  /^scroll-margin(?:-.+)?$/,
20
22
  /^scroll-padding(?:-.+)?$/,
21
23
  ],
22
- scale: [0, 4, 8, 12, 16, 24, 32, 40, 48, 64],
24
+ scale: [...DEFAULT_SCALE],
23
25
  },
24
26
  ],
25
27
  'rhythmguard/no-offscale-transform': [
@@ -1,5 +1,15 @@
1
1
  'use strict';
2
2
 
3
+ const strict = require('./strict');
4
+
5
+ // Tailwind projects: the scale is read from the project's tokens (`@theme`
6
+ // `--spacing` and `--spacing-*`, `scaleSources`, the rc), and when none are
7
+ // found it is Tailwind's default ladder, not rhythmic-4, so standard steps
8
+ // such as 20px (p-5), 28px (p-7) and 44px (p-11) are on the scale (css-01).
9
+ const SCALE = /** @type {const} */ ({ preset: 'tailwind', scale: 'auto' });
10
+ // The spacing properties strict checks; transforms stay in no-offscale-transform.
11
+ const { properties } = /** @type {any} */ (strict.rules)['rhythmguard/use-scale'][1];
12
+
3
13
  /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
4
14
  module.exports = {
5
15
  extends: [
@@ -7,6 +17,11 @@ module.exports = {
7
17
  'stylelint-plugin-rhythmguard/configs/strict',
8
18
  ],
9
19
  rules: {
20
+ 'rhythmguard/use-scale': [
21
+ true,
22
+ { properties, ...SCALE },
23
+ ],
24
+ 'rhythmguard/no-offscale-transform': [true, { ...SCALE }],
10
25
  'rhythmguard/prefer-token': [
11
26
  true,
12
27
  {
@@ -97,26 +97,39 @@ function decisionFor(px, prop, decisions) {
97
97
  }
98
98
 
99
99
  /** Decisions from the .rhythmguardrc.json in cwd, cached and revalidated by mtime. Invalid entries throw. */
100
- function loadRcDecisions(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
100
+ /** The rc decisions and why they could not be read, cached on the rc file. */
101
+ function readRcDecisions(cwd, baseFontSize) {
101
102
  const rcPath = path.join(cwd, RC_FILE);
102
103
  return cachedByFiles(`decisions:${rcPath}:${baseFontSize}`, (consult) => {
103
104
  consult(rcPath);
104
105
  if (!fs.existsSync(rcPath)) {
105
- return [];
106
+ return { decisions: [], warnings: [] };
106
107
  }
107
108
  let config;
108
109
  try {
109
110
  config = readJsonFile(rcPath);
110
- } catch {
111
- return [];
111
+ } catch (error) {
112
+ // A malformed rc loses its adopt and allow decisions: say so (cq-05).
113
+ return { decisions: [], warnings: [`${RC_FILE} could not be read, so its decisions are not applied: ${error.message}`] };
112
114
  }
113
- return normalizeDecisions(config && typeof config === 'object' ? config.decisions : undefined, { baseFontSize });
115
+ // An invalid decisions section throws, and the rules report it as a problem.
116
+ return { decisions: normalizeDecisions(config && typeof config === 'object' ? config.decisions : undefined, { baseFontSize }), warnings: [] };
114
117
  });
115
118
  }
116
119
 
120
+ function loadRcDecisions(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
121
+ return readRcDecisions(cwd, baseFontSize).decisions;
122
+ }
123
+
124
+ /** Why the rc decisions were not applied, for the lint note; empty when they were. */
125
+ function loadRcDecisionWarnings(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
126
+ return readRcDecisions(cwd, baseFontSize).warnings;
127
+ }
128
+
117
129
  module.exports = {
118
130
  DECISIONS,
119
131
  decisionFor,
132
+ loadRcDecisionWarnings,
120
133
  loadRcDecisions,
121
134
  normalizeDecisions,
122
135
  };
@@ -16,6 +16,7 @@ function fileStamp(file) {
16
16
  try {
17
17
  return fs.statSync(file).mtimeMs;
18
18
  } catch {
19
+ // Absent: a missing file has no stamp, and its absence is part of the key.
19
20
  return null;
20
21
  }
21
22
  }
@@ -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
  };