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.
- package/CHANGELOG.md +68 -0
- package/CONTRIBUTING.md +2 -2
- package/README.md +4 -4
- package/SECURITY.md +14 -0
- package/agents/claude-code/SKILL.md +14 -1
- package/agents/copilot/{copilot-instructions.md → rhythmguard.instructions.md} +7 -1
- package/agents/cursor/rhythmguard.mdc +5 -3
- package/package.json +2 -2
- package/src/audit/args.js +30 -8
- package/src/audit/baseline.js +44 -2
- package/src/audit/codemod.js +2 -0
- package/src/audit/config.js +7 -0
- package/src/audit/contract.js +131 -17
- package/src/audit/next-steps.js +86 -0
- package/src/audit/non-authored.js +1 -0
- package/src/audit/render-github.js +52 -15
- package/src/audit/render-markdown.js +58 -17
- package/src/audit/render-text.js +76 -6
- package/src/audit/render-utils.js +14 -0
- package/src/audit/report.js +235 -10
- package/src/audit/scan/files.js +5 -0
- package/src/audit/scan/stylesheets.js +63 -59
- package/src/audit/scan/templates.js +2 -0
- package/src/audit/shared.js +7 -1
- package/src/audit/token-chains.js +1 -0
- package/src/cli/audit.js +20 -11
- package/src/cli/doctor.js +853 -237
- package/src/cli/first-run.js +210 -0
- package/src/cli/index.js +25 -1
- package/src/cli/index.mjs +3 -0
- package/src/cli/init.js +75 -26
- package/src/cli/quickstart.js +109 -118
- package/src/cli/scale.js +223 -0
- package/src/configs/recommended.js +3 -1
- package/src/configs/strict.js +3 -1
- package/src/configs/tailwind.js +15 -0
- package/src/core/decisions.js +18 -5
- package/src/core/fs-cache.js +1 -0
- package/src/core/options.js +2 -1
- package/src/core/scale-inference.js +72 -52
- package/src/core/tailwind-class-analysis.js +56 -13
- package/src/core/token-index.js +55 -14
- package/src/core/token-map.js +140 -88
- package/src/core/token-sources.js +461 -40
- package/src/core/value-nodes.js +4 -2
- package/src/eslint/class-context.js +330 -0
- package/src/eslint/literal-spans.js +5 -4
- package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
- package/src/presets/default-scale.js +42 -0
- package/src/presets/scales.js +6 -1
- package/src/rules/no-offscale-transform/index.js +17 -5
- package/src/rules/prefer-token/index.js +51 -15
- package/src/rules/use-scale/index.js +7 -4
- package/types/__checks__/consumer.ts +17 -0
- package/types/__checks__/eslint-config.ts +5 -0
- package/types/audit.d.ts +42 -3
- package/types/cli.d.ts +77 -1
- 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
|
|
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
|
-
|
|
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
|
|
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
|
|
228
|
-
value
|
|
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
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
-
|
|
329
|
-
|
|
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
|
-
|
|
336
|
-
|
|
337
|
-
|
|
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
|
-
|
|
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
|
|
package/src/audit/shared.js
CHANGED
|
@@ -4,7 +4,9 @@ const path = require('node:path');
|
|
|
4
4
|
|
|
5
5
|
const pluginPath = path.resolve(__dirname, '..', 'index.js');
|
|
6
6
|
|
|
7
|
-
|
|
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 = {
|