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
@@ -27,6 +27,7 @@ function resolveScssSyntax() {
27
27
  try {
28
28
  scssSyntaxCache = require.resolve('postcss-scss', { paths: [process.cwd(), __dirname] });
29
29
  } catch {
30
+ // postcss-scss is an optional peer; without it SCSS files are counted as skipped.
30
31
  scssSyntaxCache = null;
31
32
  }
32
33
  return scssSyntaxCache;
@@ -93,6 +94,12 @@ async function runStylelintAudit(cssFiles, options) {
93
94
  severity: 'warning',
94
95
  tokenMapFromCssCustomProperties: true,
95
96
  tokenPattern: DEFAULT_AUDIT_TOKEN_PATTERN,
97
+ // The token definitions the audit resolved (token sources and the
98
+ // stylesheets that declare tokens), so the message names the token
99
+ // and its file instead of "No known token holds this value" (dx-08).
100
+ ...(Array.isArray(options.tokenScaleSources) && options.tokenScaleSources.length > 0
101
+ ? { scaleSources: options.tokenScaleSources }
102
+ : {}),
96
103
  },
97
104
  ],
98
105
  };
@@ -155,6 +162,7 @@ async function lintSources(stylelint, files, config, readSource) {
155
162
  try {
156
163
  code = readSource(file);
157
164
  } catch {
165
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
158
166
  continue;
159
167
  }
160
168
  const result = await stylelint.lint({ allowEmptyInput: true, code, codeFilename: file, config });
@@ -211,18 +219,7 @@ function collectCssFindings(fileResults, readSource) {
211
219
  continue;
212
220
  }
213
221
  const source = readSourceOnce(sources, fileResult.source, readSource);
214
- const offScaleMatch = text.match(
215
- /Unexpected (?:off-scale (?:value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument))|transform translation value) "([^"]+)"/,
216
- );
217
- const tokenMatch = text.match(
218
- /Unexpected raw (?:scale value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument)) "([^"]+)"/,
219
- );
220
- const motionDurationMatch = text.match(
221
- /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,
222
- );
223
- const motionEasingMatch = text.match(
224
- /Unexpected raw motion easing "([^"]+)"/,
225
- );
222
+ const { type, value } = classifyCssWarningText(text);
226
223
 
227
224
  findings.push({
228
225
  column: warning.column || 1,
@@ -233,13 +230,8 @@ function collectCssFindings(fileResults, readSource) {
233
230
  : findDeclarationProperty(source, warning.line || 1, warning.column || 1),
234
231
  rule: warning.rule || 'rhythmguard',
235
232
  text,
236
- type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
237
- value: getCssFindingValue({
238
- motionDurationMatch,
239
- motionEasingMatch,
240
- offScaleMatch,
241
- tokenMatch,
242
- }),
233
+ type,
234
+ value,
243
235
  });
244
236
  }
245
237
  }
@@ -255,6 +247,7 @@ function readSourceOnce(cache, filePath, readSource = readSourceFromDisk) {
255
247
  try {
256
248
  cache.set(filePath, readSource(filePath));
257
249
  } catch {
250
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
258
251
  cache.set(filePath, null);
259
252
  }
260
253
  }
@@ -316,48 +309,50 @@ function positionToOffset(source, line, column) {
316
309
  return offset + Math.min(Math.max((column || 1) - 1, 0), lineLength);
317
310
  }
318
311
 
319
- function getCssFindingValue({
320
- motionDurationMatch,
321
- motionEasingMatch,
322
- offScaleMatch,
323
- tokenMatch,
324
- }) {
325
- if (tokenMatch) {
326
- return tokenMatch[1];
327
- }
328
-
329
- if (offScaleMatch) {
330
- return offScaleMatch[1];
331
- }
332
-
333
- if (motionDurationMatch) {
334
- return motionDurationMatch[1];
335
- }
312
+ /**
313
+ * The message shapes the audit reads back into findings, each with the type
314
+ * it becomes. Stylelint reports positions and text, not structured data, so
315
+ * these follow the message templates in src/rules; the contract test
316
+ * test/contracts/finding-messages.test.js calls every template and checks
317
+ * that each one is parsed here or listed there as deliberately unclassified.
318
+ */
319
+ const FINDING_PATTERNS = Object.freeze([
320
+ ['motion-duration', /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/],
321
+ ['motion-easing', /Unexpected raw motion easing "([^"]+)"/],
322
+ ['token-opportunity', /Unexpected raw (?:scale value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument)) "([^"]+)"/],
323
+ // Followed by the advice, so a forbidden negative or percentage, which names no scale step, is not read as off-scale.
324
+ ['off-scale', /Unexpected (?:off-scale|transform translation) (?:value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument)) "([^"]+)"(?: \([^)]*\))?\. Use /],
325
+ ]);
336
326
 
337
- if (motionEasingMatch) {
338
- return motionEasingMatch[1];
327
+ /**
328
+ * The finding type and value of one Stylelint warning. A message none of the
329
+ * patterns reads (a root-level configuration report, or a template the audit
330
+ * does not know) is `unclassified` with no value: it is still a finding, but
331
+ * it is not counted as an off-scale value it may not be (cq-02).
332
+ */
333
+ function classifyCssWarningText(text) {
334
+ for (const [type, pattern] of FINDING_PATTERNS) {
335
+ const match = String(text || '').match(pattern);
336
+ if (match) {
337
+ return { type, value: match[1] };
338
+ }
339
339
  }
340
-
341
- return null;
340
+ return { type: 'unclassified', value: null };
342
341
  }
343
342
 
344
- function getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }) {
345
- if (motionDurationMatch) {
346
- return 'motion-duration';
347
- }
348
-
349
- if (motionEasingMatch) {
350
- return 'motion-easing';
351
- }
352
-
353
- if (tokenMatch) {
354
- return 'token-opportunity';
355
- }
343
+ /** The finding type of a warning's text (see classifyCssWarningText). */
344
+ function getCssFindingType(text) {
345
+ return classifyCssWarningText(text).type;
346
+ }
356
347
 
357
- return 'off-scale';
348
+ /** The value a warning's text names, or null (see classifyCssWarningText). */
349
+ function getCssFindingValue(text) {
350
+ return classifyCssWarningText(text).value;
358
351
  }
359
352
 
360
353
  module.exports = {
354
+ FINDING_PATTERNS,
355
+ classifyCssWarningText,
361
356
  collectCssFindings,
362
357
  findDeclarationProperty,
363
358
  getCssFindingType,
@@ -22,6 +22,7 @@ function collectTailwindFindings(templateFiles, options) {
22
22
  try {
23
23
  source = options.readSource ? options.readSource(filePath) : fs.readFileSync(filePath, 'utf8');
24
24
  } catch {
25
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
25
26
  continue;
26
27
  }
27
28
 
@@ -68,6 +69,7 @@ function collectTailwindMotionFindings(templateFiles, options) {
68
69
  try {
69
70
  source = options.readSource ? options.readSource(filePath) : fs.readFileSync(filePath, 'utf8');
70
71
  } catch {
72
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
71
73
  continue;
72
74
  }
73
75
 
@@ -4,7 +4,9 @@ const path = require('node:path');
4
4
 
5
5
  const pluginPath = path.resolve(__dirname, '..', 'index.js');
6
6
 
7
- const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
7
+ // One default with the rules and configs/recommended (dx-06): before 3.20 the
8
+ // audit stopped at 32, so 40, 48 and 64px were off-scale here and on-scale in Stylelint.
9
+ const { DEFAULT_SCALE } = require('../presets/default-scale');
8
10
 
9
11
  const DEFAULT_BASE_FONT_SIZE = 16;
10
12
 
@@ -69,9 +71,11 @@ function createDefaultAuditOptions() {
69
71
  configPath: DEFAULT_CONFIG_PATH,
70
72
  dir: null,
71
73
  failOnNewDrift: false,
74
+ failOnNewTokenDebt: false,
72
75
  badgeMetric: 'drift',
73
76
  decisions: [],
74
77
  plan: false,
78
+ reportMissingTokens: false,
75
79
  format: 'text',
76
80
  ignorePath: DEFAULT_IGNORE_PATH,
77
81
  ignorePatterns: [],
@@ -89,6 +93,8 @@ function createDefaultAuditOptions() {
89
93
  since: null,
90
94
  sinceBaseline: false,
91
95
  staged: false,
96
+ // CLI flag or API only, never the rc: a repository file must not make the audit run code.
97
+ tailwindConfigPath: null,
92
98
  tokenCandidateMinCount: DEFAULT_TOKEN_CANDIDATE_MIN_COUNT,
93
99
  tokenKind: 'spacing',
94
100
  tokenSourceFormat: 'auto',
@@ -48,6 +48,7 @@ function collectDeclarations({ cssFiles, externalDefinitions, readSource = (file
48
48
  try {
49
49
  source = readSource(filePath);
50
50
  } catch {
51
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
51
52
  continue;
52
53
  }
53
54
  const lineComments = hasLineComments(filePath);
package/src/cli/audit.js CHANGED
@@ -114,9 +114,9 @@ function writeOutput(output, outputPath) {
114
114
  function finish(auditFailures, report) {
115
115
  // A configured token source that does not exist made the run audit against
116
116
  // another scale and pass (ci-02): that is a configuration error, exit 2.
117
- const missing = ((report && report.tokenSourceWarnings) || []).filter((warning) => warning.startsWith('Token source not found:'));
117
+ const missing = ((report && report.tokenSourceWarnings) || []).filter((warning) => warning.startsWith('Token source not found:') || warning.startsWith('Tailwind config not found:'));
118
118
  if (missing.length > 0) {
119
- process.stderr.write(`${missing.join('\n')}\nAudit failed: a 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`);
119
+ process.stderr.write(`${missing.join('\n')}\nAudit failed: a configured token source does not exist, so the scale above is not the one configured. Fix the path in --token-source, --tailwind-config, audit.tokenSources or audit.tailwindConfigPath.\n`);
120
120
  process.exitCode = 2;
121
121
  }
122
122