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
@@ -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;
@@ -35,18 +36,15 @@ function resolveScssSyntax() {
35
36
  /**
36
37
  * Stylelint is an optional peer, so an ESLint-only project can reach this
37
38
  * without it. The `rhythmguard` package depends on it; this package's own
38
- * command says what to install instead of failing on a module path.
39
+ * command then audits class strings only and counts the stylesheets as not
40
+ * audited (null here), instead of failing on a module path.
39
41
  */
40
42
  async function loadStylelint() {
41
43
  try {
42
44
  return (await import('stylelint')).default;
43
45
  } catch (error) {
44
46
  if (error && error.code === 'ERR_MODULE_NOT_FOUND' && /'stylelint'/.test(error.message)) {
45
- throw new Error(
46
- 'Auditing stylesheets needs Stylelint, which this project does not have. '
47
- + 'Install it with: npm install --save-dev stylelint',
48
- { cause: error },
49
- );
47
+ return null;
50
48
  }
51
49
  throw error;
52
50
  }
@@ -58,11 +56,22 @@ async function runStylelintAudit(cssFiles, options) {
58
56
  empty.scssFiles = 0;
59
57
  empty.scssSkipped = 0;
60
58
  empty.stylelintIgnored = 0;
59
+ empty.stylelintMissing = 0;
61
60
  empty.unauditedFiles = [];
62
61
  return empty;
63
62
  }
64
63
 
65
64
  const stylelint = await loadStylelint();
65
+ if (!stylelint) {
66
+ // Found but not audited, like SCSS without postcss-scss: neither scanned nor clean.
67
+ const missing = [];
68
+ missing.scssFiles = 0;
69
+ missing.scssSkipped = 0;
70
+ missing.stylelintIgnored = 0;
71
+ missing.stylelintMissing = cssFiles.length;
72
+ missing.unauditedFiles = [...cssFiles];
73
+ return missing;
74
+ }
66
75
  const rules = {
67
76
  'rhythmguard/use-scale': [
68
77
  true,
@@ -85,6 +94,12 @@ async function runStylelintAudit(cssFiles, options) {
85
94
  severity: 'warning',
86
95
  tokenMapFromCssCustomProperties: true,
87
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
+ : {}),
88
103
  },
89
104
  ],
90
105
  };
@@ -133,6 +148,7 @@ async function runStylelintAudit(cssFiles, options) {
133
148
  results.scssFiles = scssFiles.length;
134
149
  results.scssSkipped = skippedScssFiles.length;
135
150
  results.stylelintIgnored = ignoredFiles.length;
151
+ results.stylelintMissing = 0;
136
152
  // Neither kind was audited: they count as neither scanned nor clean.
137
153
  results.unauditedFiles = [...skippedScssFiles, ...ignoredFiles];
138
154
  return results;
@@ -146,6 +162,7 @@ async function lintSources(stylelint, files, config, readSource) {
146
162
  try {
147
163
  code = readSource(file);
148
164
  } catch {
165
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
149
166
  continue;
150
167
  }
151
168
  const result = await stylelint.lint({ allowEmptyInput: true, code, codeFilename: file, config });
@@ -202,18 +219,7 @@ function collectCssFindings(fileResults, readSource) {
202
219
  continue;
203
220
  }
204
221
  const source = readSourceOnce(sources, fileResult.source, readSource);
205
- const offScaleMatch = text.match(
206
- /Unexpected (?:off-scale (?:value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument))|transform translation value) "([^"]+)"/,
207
- );
208
- const tokenMatch = text.match(
209
- /Unexpected raw (?:scale value|(?:clamp|min|max)\(\) (?:minimum|maximum|argument)) "([^"]+)"/,
210
- );
211
- const motionDurationMatch = text.match(
212
- /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,
213
- );
214
- const motionEasingMatch = text.match(
215
- /Unexpected raw motion easing "([^"]+)"/,
216
- );
222
+ const { type, value } = classifyCssWarningText(text);
217
223
 
218
224
  findings.push({
219
225
  column: warning.column || 1,
@@ -224,13 +230,8 @@ function collectCssFindings(fileResults, readSource) {
224
230
  : findDeclarationProperty(source, warning.line || 1, warning.column || 1),
225
231
  rule: warning.rule || 'rhythmguard',
226
232
  text,
227
- type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
228
- value: getCssFindingValue({
229
- motionDurationMatch,
230
- motionEasingMatch,
231
- offScaleMatch,
232
- tokenMatch,
233
- }),
233
+ type,
234
+ value,
234
235
  });
235
236
  }
236
237
  }
@@ -246,6 +247,7 @@ function readSourceOnce(cache, filePath, readSource = readSourceFromDisk) {
246
247
  try {
247
248
  cache.set(filePath, readSource(filePath));
248
249
  } catch {
250
+ // Unreadable since the scan (deleted, permissions): this pass reads only what it can.
249
251
  cache.set(filePath, null);
250
252
  }
251
253
  }
@@ -307,48 +309,50 @@ function positionToOffset(source, line, column) {
307
309
  return offset + Math.min(Math.max((column || 1) - 1, 0), lineLength);
308
310
  }
309
311
 
310
- function getCssFindingValue({
311
- motionDurationMatch,
312
- motionEasingMatch,
313
- offScaleMatch,
314
- tokenMatch,
315
- }) {
316
- if (tokenMatch) {
317
- return tokenMatch[1];
318
- }
319
-
320
- if (offScaleMatch) {
321
- return offScaleMatch[1];
322
- }
323
-
324
- if (motionDurationMatch) {
325
- return motionDurationMatch[1];
326
- }
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
+ ]);
327
326
 
328
- if (motionEasingMatch) {
329
- 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
+ }
330
339
  }
331
-
332
- return null;
340
+ return { type: 'unclassified', value: null };
333
341
  }
334
342
 
335
- function getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }) {
336
- if (motionDurationMatch) {
337
- return 'motion-duration';
338
- }
339
-
340
- if (motionEasingMatch) {
341
- return 'motion-easing';
342
- }
343
-
344
- if (tokenMatch) {
345
- return 'token-opportunity';
346
- }
343
+ /** The finding type of a warning's text (see classifyCssWarningText). */
344
+ function getCssFindingType(text) {
345
+ return classifyCssWarningText(text).type;
346
+ }
347
347
 
348
- return 'off-scale';
348
+ /** The value a warning's text names, or null (see classifyCssWarningText). */
349
+ function getCssFindingValue(text) {
350
+ return classifyCssWarningText(text).value;
349
351
  }
350
352
 
351
353
  module.exports = {
354
+ FINDING_PATTERNS,
355
+ classifyCssWarningText,
352
356
  collectCssFindings,
353
357
  findDeclarationProperty,
354
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
@@ -16,6 +16,7 @@ const { renderGithub } = require('../audit/render-github');
16
16
  const { renderBadge } = require('../audit/render-badge');
17
17
  const { renderHtml } = require('../audit/render-html');
18
18
  const { renderMarkdown } = require('../audit/render-markdown');
19
+ const { auditCommandFromArgs } = require('../audit/next-steps');
19
20
  const { renderText } = require('../audit/render-text');
20
21
  const { createAuditReport, normalizeCreateAuditOptions } = require('../audit/report');
21
22
 
@@ -61,42 +62,42 @@ async function run() {
61
62
 
62
63
  if (parsed.format === 'json') {
63
64
  writeOutput(`${JSON.stringify(toAuditContractReport(report), null, 2)}\n`, parsed.outputPath);
64
- finish(auditFailures);
65
+ finish(auditFailures, report);
65
66
  return;
66
67
  }
67
68
 
68
69
  if (parsed.format === 'json-v1') {
69
70
  writeOutput(`${JSON.stringify(report, null, 2)}\n`, parsed.outputPath);
70
- finish(auditFailures);
71
+ finish(auditFailures, report);
71
72
  return;
72
73
  }
73
74
 
74
75
  if (parsed.format === 'markdown') {
75
- writeOutput(renderMarkdown(report), parsed.outputPath);
76
- finish(auditFailures);
76
+ writeOutput(renderMarkdown(report, { auditCommand: auditCommandFromArgs(parsed) }), parsed.outputPath);
77
+ finish(auditFailures, report);
77
78
  return;
78
79
  }
79
80
 
80
81
  if (parsed.format === 'html') {
81
82
  writeOutput(renderHtml(report), parsed.outputPath);
82
- finish(auditFailures);
83
+ finish(auditFailures, report);
83
84
  return;
84
85
  }
85
86
 
86
87
  if (parsed.format === 'badge') {
87
88
  writeOutput(renderBadge(report, { metric: parsed.badgeMetric }), parsed.outputPath);
88
- finish(auditFailures);
89
+ finish(auditFailures, report);
89
90
  return;
90
91
  }
91
92
 
92
93
  if (parsed.format === 'github') {
93
94
  writeOutput(renderGithub(report), parsed.outputPath);
94
- finish(auditFailures);
95
+ finish(auditFailures, report);
95
96
  return;
96
97
  }
97
98
 
98
- writeOutput(renderText(report), parsed.outputPath);
99
- finish(auditFailures);
99
+ writeOutput(renderText(report, { auditCommand: auditCommandFromArgs(parsed) }), parsed.outputPath);
100
+ finish(auditFailures, report);
100
101
  }
101
102
 
102
103
  function writeOutput(output, outputPath) {
@@ -110,13 +111,21 @@ function writeOutput(output, outputPath) {
110
111
  fs.writeFileSync(resolvedPath, output);
111
112
  }
112
113
 
113
- function finish(auditFailures) {
114
+ function finish(auditFailures, report) {
115
+ // A configured token source that does not exist made the run audit against
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:') || warning.startsWith('Tailwind config not found:'));
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, --tailwind-config, audit.tokenSources or audit.tailwindConfigPath.\n`);
120
+ process.exitCode = 2;
121
+ }
122
+
114
123
  if (auditFailures.length === 0) {
115
124
  return;
116
125
  }
117
126
 
118
127
  process.stderr.write(`Audit failed: ${auditFailures.join('; ')}\n`);
119
- process.exitCode = 1;
128
+ process.exitCode = process.exitCode || 1;
120
129
  }
121
130
 
122
131
  module.exports = {