stylelint-plugin-rhythmguard 3.17.0 → 3.19.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 +48 -0
- package/CONTRIBUTING.md +7 -7
- package/README.md +16 -2
- package/SECURITY.md +13 -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 +3 -3
- package/src/audit/baseline.js +8 -0
- package/src/audit/contract.js +7 -3
- package/src/audit/next-steps.js +84 -0
- package/src/audit/render-github.js +46 -14
- package/src/audit/render-markdown.js +50 -15
- package/src/audit/render-text.js +35 -4
- package/src/audit/report.js +5 -0
- package/src/audit/scan/stylesheets.js +15 -6
- package/src/cli/audit.js +20 -11
- package/src/cli/init.js +39 -18
- package/src/cli/quickstart.js +65 -25
- package/src/core/token-map.js +4 -60
- package/src/core/token-packages.json +8 -0
- package/src/core/token-sources.js +28 -2
- package/types/audit.d.ts +2 -0
package/src/audit/render-text.js
CHANGED
|
@@ -4,13 +4,18 @@ const {
|
|
|
4
4
|
sortCountMap,
|
|
5
5
|
sumCounts,
|
|
6
6
|
} = require('./contract');
|
|
7
|
+
const { auditCommand, shellQuote } = require('./next-steps');
|
|
7
8
|
const {
|
|
8
9
|
histBar,
|
|
9
10
|
scoreBar,
|
|
10
11
|
truncate,
|
|
11
12
|
} = require('./render-utils');
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
/**
|
|
15
|
+
* `options.auditCommand` is the command that reproduces this run (its directory
|
|
16
|
+
* and scale flags); the footer builds on it so the next step uses the same scale.
|
|
17
|
+
*/
|
|
18
|
+
function renderText(report, options = {}) {
|
|
14
19
|
const lines = [
|
|
15
20
|
'',
|
|
16
21
|
' ┌─ RHYTHMGUARD DESIGN-SYSTEM AUDIT ─────────────────────────┐',
|
|
@@ -21,6 +26,7 @@ function renderText(report) {
|
|
|
21
26
|
` Template files scanned ${String(report.templateFilesScanned).padStart(4)}`,
|
|
22
27
|
...(report.scanned && report.scanned.scssFiles > 0 ? [` SCSS files scanned ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
|
|
23
28
|
...(report.scanned && report.scanned.scssSkipped > 0 ? [` SCSS files skipped ${String(report.scanned.scssSkipped).padStart(4)} (install postcss-scss to audit them)`] : []),
|
|
29
|
+
...(report.scanned && report.scanned.stylelintMissing > 0 ? [` Stylesheets not audited ${String(report.scanned.stylelintMissing).padStart(4)} (Stylelint is not installed: npm install --save-dev stylelint)`] : []),
|
|
24
30
|
...(report.scanned && report.scanned.stylelintIgnored > 0 ? [` Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)} (not audited)`] : []),
|
|
25
31
|
...(report.scanned && report.scanned.nonAuthoredSkipped > 0 ? [` Non-authored skipped ${String(report.scanned.nonAuthoredSkipped).padStart(4)} (vendored, minified or built CSS; --include-non-authored audits them)`] : []),
|
|
26
32
|
...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [` Links not followed ${String(report.scanned.linksOutsideRoot).padStart(4)} (they point outside the scanned directory)`] : []),
|
|
@@ -72,19 +78,42 @@ function renderText(report) {
|
|
|
72
78
|
lines.push('');
|
|
73
79
|
}
|
|
74
80
|
|
|
75
|
-
if (
|
|
81
|
+
if (nothingAudited(report)) {
|
|
82
|
+
lines.push(` ! Nothing was audited: ${nothingAuditedReasons(report).join('; ')}. The cleanliness above counts no files.`);
|
|
83
|
+
} else if (report.totalWarnings === 0 && parseErrors(report).length > 0) {
|
|
76
84
|
lines.push(` ! No findings in the stylesheets that parsed; ${parseErrors(report).length} could not be parsed and were not audited.`);
|
|
77
85
|
} else if (report.totalWarnings === 0) {
|
|
78
86
|
lines.push(' ✓ No issues found. Your design-system rhythm is clean.');
|
|
79
87
|
} else {
|
|
80
|
-
|
|
81
|
-
|
|
88
|
+
// Snapping a value can move layout, so the footer offers the reviewable
|
|
89
|
+
// path: one decision per value, then a rewrite of each decided value.
|
|
90
|
+
const command = options.auditCommand || auditCommand({ dir: report.directory });
|
|
91
|
+
lines.push(` → Propose one decision per off-scale value: ${command} --plan`);
|
|
92
|
+
lines.push(` → Then rewrite each value you decided on: npx rhythmguard fix ${shellQuote(report.directory)} --value <px> --to <step or token>`);
|
|
93
|
+
lines.push(` → PR or design review: ${command} --format markdown`);
|
|
82
94
|
}
|
|
83
95
|
lines.push('');
|
|
84
96
|
|
|
85
97
|
return `${lines.join('\n')}\n`;
|
|
86
98
|
}
|
|
87
99
|
|
|
100
|
+
/** No stylesheet and no template file was read, though the run may have found some (dx-09). */
|
|
101
|
+
function nothingAudited(report) {
|
|
102
|
+
return (report.cssFilesScanned || 0) === 0 && (report.templateFilesScanned || 0) === 0;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function nothingAuditedReasons(report) {
|
|
106
|
+
const scanned = report.scanned || {};
|
|
107
|
+
const reasons = [
|
|
108
|
+
...(scanned.stylelintMissing > 0 ? [`${scanned.stylelintMissing} stylesheets need Stylelint, which is not installed`] : []),
|
|
109
|
+
...(scanned.scssSkipped > 0 ? [`${scanned.scssSkipped} SCSS files need postcss-scss, which is not installed`] : []),
|
|
110
|
+
...(scanned.stylelintIgnored > 0 ? [`${scanned.stylelintIgnored} stylesheets are in .stylelintignore`] : []),
|
|
111
|
+
...(scanned.nonAuthoredSkipped > 0 ? [`${scanned.nonAuthoredSkipped} stylesheets look vendored, minified or built`] : []),
|
|
112
|
+
...(parseErrors(report).length > 0 ? [`${parseErrors(report).length} stylesheets could not be parsed`] : []),
|
|
113
|
+
];
|
|
114
|
+
return reasons.length > 0 ? reasons : [`no .css, .scss or template files under ${report.directory}`];
|
|
115
|
+
}
|
|
116
|
+
|
|
88
117
|
function parseErrors(report) {
|
|
89
118
|
return (report.findings && report.findings.parseErrors) || [];
|
|
90
119
|
}
|
|
@@ -208,6 +237,8 @@ function appendHistogram(lines, title, counts = {}) {
|
|
|
208
237
|
}
|
|
209
238
|
|
|
210
239
|
module.exports = {
|
|
240
|
+
nothingAudited,
|
|
241
|
+
nothingAuditedReasons,
|
|
211
242
|
appendBaselineText,
|
|
212
243
|
appendHistogram,
|
|
213
244
|
appendParseErrorsText,
|
package/src/audit/report.js
CHANGED
|
@@ -126,6 +126,7 @@ async function createAuditReport(options) {
|
|
|
126
126
|
scssFiles: cssResults.scssFiles || 0,
|
|
127
127
|
scssSkipped: cssResults.scssSkipped || 0,
|
|
128
128
|
stylelintIgnored: cssResults.stylelintIgnored || 0,
|
|
129
|
+
stylelintMissing: cssResults.stylelintMissing || 0,
|
|
129
130
|
tailwindFindings: decided.tailwindFindings,
|
|
130
131
|
templateFiles,
|
|
131
132
|
tokenCandidateMinCount: parsed.tokenCandidateMinCount,
|
|
@@ -134,6 +135,10 @@ async function createAuditReport(options) {
|
|
|
134
135
|
tokenSourceWarnings: tokenSourceResult.warnings,
|
|
135
136
|
});
|
|
136
137
|
|
|
138
|
+
// The files this run scanned, for the CLI's next-step commands (lint globs,
|
|
139
|
+
// parsers). Not enumerable, so no JSON output carries the lists.
|
|
140
|
+
Object.defineProperty(report, 'files', { enumerable: false, value: { cssFiles: [...cssFiles], templateFiles: [...templateFiles] } });
|
|
141
|
+
|
|
137
142
|
const declarations = collectDeclarations({
|
|
138
143
|
cssFiles,
|
|
139
144
|
externalDefinitions: tokenSourceResult.definitions,
|
|
@@ -35,18 +35,15 @@ function resolveScssSyntax() {
|
|
|
35
35
|
/**
|
|
36
36
|
* Stylelint is an optional peer, so an ESLint-only project can reach this
|
|
37
37
|
* without it. The `rhythmguard` package depends on it; this package's own
|
|
38
|
-
* command
|
|
38
|
+
* command then audits class strings only and counts the stylesheets as not
|
|
39
|
+
* audited (null here), instead of failing on a module path.
|
|
39
40
|
*/
|
|
40
41
|
async function loadStylelint() {
|
|
41
42
|
try {
|
|
42
43
|
return (await import('stylelint')).default;
|
|
43
44
|
} catch (error) {
|
|
44
45
|
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
|
-
);
|
|
46
|
+
return null;
|
|
50
47
|
}
|
|
51
48
|
throw error;
|
|
52
49
|
}
|
|
@@ -58,11 +55,22 @@ async function runStylelintAudit(cssFiles, options) {
|
|
|
58
55
|
empty.scssFiles = 0;
|
|
59
56
|
empty.scssSkipped = 0;
|
|
60
57
|
empty.stylelintIgnored = 0;
|
|
58
|
+
empty.stylelintMissing = 0;
|
|
61
59
|
empty.unauditedFiles = [];
|
|
62
60
|
return empty;
|
|
63
61
|
}
|
|
64
62
|
|
|
65
63
|
const stylelint = await loadStylelint();
|
|
64
|
+
if (!stylelint) {
|
|
65
|
+
// Found but not audited, like SCSS without postcss-scss: neither scanned nor clean.
|
|
66
|
+
const missing = [];
|
|
67
|
+
missing.scssFiles = 0;
|
|
68
|
+
missing.scssSkipped = 0;
|
|
69
|
+
missing.stylelintIgnored = 0;
|
|
70
|
+
missing.stylelintMissing = cssFiles.length;
|
|
71
|
+
missing.unauditedFiles = [...cssFiles];
|
|
72
|
+
return missing;
|
|
73
|
+
}
|
|
66
74
|
const rules = {
|
|
67
75
|
'rhythmguard/use-scale': [
|
|
68
76
|
true,
|
|
@@ -133,6 +141,7 @@ async function runStylelintAudit(cssFiles, options) {
|
|
|
133
141
|
results.scssFiles = scssFiles.length;
|
|
134
142
|
results.scssSkipped = skippedScssFiles.length;
|
|
135
143
|
results.stylelintIgnored = ignoredFiles.length;
|
|
144
|
+
results.stylelintMissing = 0;
|
|
136
145
|
// Neither kind was audited: they count as neither scanned nor clean.
|
|
137
146
|
results.unauditedFiles = [...skippedScssFiles, ...ignoredFiles];
|
|
138
147
|
return results;
|
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:'));
|
|
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`);
|
|
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 = {
|
package/src/cli/init.js
CHANGED
|
@@ -2,6 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
const fs = require('node:fs');
|
|
4
4
|
const path = require('node:path');
|
|
5
|
+
|
|
6
|
+
const { lintGlob, stylelintInstallLine } = require('../audit/next-steps');
|
|
7
|
+
const { getScanFiles } = require('../audit/scan/files');
|
|
5
8
|
const readline = require('node:readline');
|
|
6
9
|
|
|
7
10
|
function createPrompter() {
|
|
@@ -195,7 +198,7 @@ function selectProfile(stack) {
|
|
|
195
198
|
const AGENT_TARGETS = {
|
|
196
199
|
claude: { source: 'claude-code/SKILL.md', target: path.join('.claude', 'skills', 'rhythmguard', 'SKILL.md'), mode: 'write' },
|
|
197
200
|
cursor: { source: 'cursor/rhythmguard.mdc', target: path.join('.cursor', 'rules', 'rhythmguard.mdc'), mode: 'write' },
|
|
198
|
-
copilot: { source: 'copilot/
|
|
201
|
+
copilot: { source: 'copilot/rhythmguard.instructions.md', target: path.join('.github', 'instructions', 'rhythmguard.instructions.md'), mode: 'write' },
|
|
199
202
|
};
|
|
200
203
|
const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
|
|
201
204
|
const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
|
|
@@ -238,11 +241,31 @@ function parseInitArgs(argv) {
|
|
|
238
241
|
return parsed;
|
|
239
242
|
}
|
|
240
243
|
|
|
244
|
+
/**
|
|
245
|
+
* Up to 3.18 the Copilot pack was appended to .github/copilot-instructions.md
|
|
246
|
+
* between markers. It now has its own path-specific file, so the old block,
|
|
247
|
+
* which this command wrote and owns, is taken out to leave one copy.
|
|
248
|
+
*/
|
|
249
|
+
function removeLegacyCopilotBlock(cwd) {
|
|
250
|
+
const legacy = path.join('.github', 'copilot-instructions.md');
|
|
251
|
+
const legacyPath = path.join(cwd, legacy);
|
|
252
|
+
if (!fs.existsSync(legacyPath)) return null;
|
|
253
|
+
const existing = fs.readFileSync(legacyPath, 'utf8');
|
|
254
|
+
const start = existing.indexOf(AGENT_BLOCK_START);
|
|
255
|
+
const end = existing.indexOf(AGENT_BLOCK_END);
|
|
256
|
+
if (start === -1 || end === -1 || end < start) return null;
|
|
257
|
+
const next = `${existing.slice(0, start).trimEnd()}\n${existing.slice(end + AGENT_BLOCK_END.length).replace(/^\n+/, '\n')}`.replace(/^\n+/, '');
|
|
258
|
+
if (next.trim() === '') {
|
|
259
|
+
fs.rmSync(legacyPath);
|
|
260
|
+
} else {
|
|
261
|
+
fs.writeFileSync(legacyPath, next.endsWith('\n') ? next : `${next}\n`);
|
|
262
|
+
}
|
|
263
|
+
return legacy;
|
|
264
|
+
}
|
|
265
|
+
|
|
241
266
|
/**
|
|
242
267
|
* Copies the generated packs under <package>/agents into the locations each
|
|
243
|
-
* agent reads.
|
|
244
|
-
* overwritten; copilot-instructions.md is shared, so the block is appended
|
|
245
|
-
* between markers and replaced in place on later runs.
|
|
268
|
+
* agent reads. Every target is a file Rhythmguard owns, overwritten on rerun.
|
|
246
269
|
*/
|
|
247
270
|
function installAgents(selection, cwd = process.cwd()) {
|
|
248
271
|
const names = selection === 'all' ? Object.keys(AGENT_TARGETS) : [selection];
|
|
@@ -254,24 +277,17 @@ function installAgents(selection, cwd = process.cwd()) {
|
|
|
254
277
|
const packsDir = path.join(__dirname, '..', '..', 'agents');
|
|
255
278
|
const written = [];
|
|
256
279
|
for (const name of names) {
|
|
257
|
-
const {
|
|
280
|
+
const { source, target } = AGENT_TARGETS[name];
|
|
258
281
|
const content = fs.readFileSync(path.join(packsDir, source), 'utf8');
|
|
259
282
|
const targetPath = path.join(cwd, target);
|
|
260
283
|
fs.mkdirSync(path.dirname(targetPath), { recursive: true });
|
|
261
284
|
|
|
262
|
-
|
|
263
|
-
const existing = fs.readFileSync(targetPath, 'utf8');
|
|
264
|
-
const block = `${AGENT_BLOCK_START}\n${content.trimEnd()}\n${AGENT_BLOCK_END}\n`;
|
|
265
|
-
const start = existing.indexOf(AGENT_BLOCK_START);
|
|
266
|
-
const end = existing.indexOf(AGENT_BLOCK_END);
|
|
267
|
-
const next = start !== -1 && end !== -1
|
|
268
|
-
? `${existing.slice(0, start)}${block}${existing.slice(end + AGENT_BLOCK_END.length).replace(/^\n/, '')}`
|
|
269
|
-
: `${existing.trimEnd()}\n\n${block}`;
|
|
270
|
-
fs.writeFileSync(targetPath, next);
|
|
271
|
-
} else {
|
|
272
|
-
fs.writeFileSync(targetPath, content);
|
|
273
|
-
}
|
|
285
|
+
fs.writeFileSync(targetPath, content);
|
|
274
286
|
written.push(target);
|
|
287
|
+
if (name === 'copilot') {
|
|
288
|
+
const moved = removeLegacyCopilotBlock(cwd);
|
|
289
|
+
if (moved) written.push(`${moved} (the block an older version appended there was removed)`);
|
|
290
|
+
}
|
|
275
291
|
}
|
|
276
292
|
return written;
|
|
277
293
|
}
|
|
@@ -324,8 +340,12 @@ async function run() {
|
|
|
324
340
|
}
|
|
325
341
|
|
|
326
342
|
const profile = selectProfile(stack);
|
|
343
|
+
// The stylesheets here decide the glob, and whether SCSS needs its syntax (dx-05, dx-10).
|
|
344
|
+
const stylesheets = getScanFiles(process.cwd(), [], {}).cssFiles;
|
|
345
|
+
const scss = stylesheets.some((file) => file.endsWith('.scss'));
|
|
327
346
|
const config = {
|
|
328
347
|
extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
|
|
348
|
+
...(scss ? { customSyntax: 'postcss-scss' } : {}),
|
|
329
349
|
// Next.js build output is generated CSS; never lint it.
|
|
330
350
|
...(stack.nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
|
|
331
351
|
};
|
|
@@ -372,7 +392,8 @@ async function run() {
|
|
|
372
392
|
|
|
373
393
|
process.stdout.write(`\n✓ Wrote ${configPath}\n`);
|
|
374
394
|
process.stdout.write(`\nNext steps:\n`);
|
|
375
|
-
process.stdout.write(`
|
|
395
|
+
process.stdout.write(` ${stylelintInstallLine({ scss, tailwindConfig: profile === 'tailwind' })}\n`);
|
|
396
|
+
process.stdout.write(` npx stylelint "${lintGlob(process.cwd(), stylesheets)}"\n\n`);
|
|
376
397
|
} finally {
|
|
377
398
|
prompter.close();
|
|
378
399
|
}
|
package/src/cli/quickstart.js
CHANGED
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
const fs = require('node:fs');
|
|
13
13
|
const path = require('node:path');
|
|
14
14
|
|
|
15
|
+
const { auditCommand, eslintInstallLine, lintGlob, stylelintInstallLine } = require('../audit/next-steps');
|
|
15
16
|
const { createAuditReport } = require('../audit/report');
|
|
16
17
|
const { detect } = require('./init');
|
|
17
18
|
const { discoverTokenPackages } = require('../core/scale-inference');
|
|
@@ -94,13 +95,15 @@ function topEntries(counts, limit = MAX_LISTED) {
|
|
|
94
95
|
* `scale: "auto"` would fall back to the `rhythmic-4` preset instead, which is
|
|
95
96
|
* a longer scale, and the pasted config would not reproduce this report (#246).
|
|
96
97
|
*/
|
|
97
|
-
function suggestedStylelintConfig({ fallbackScale = null, nextjs = false, profile, tokenFiles }) {
|
|
98
|
+
function suggestedStylelintConfig({ fallbackScale = null, nextjs = false, profile, scss = false, tokenFiles }) {
|
|
98
99
|
const ruleOptions = Array.isArray(fallbackScale) ? { scale: [...fallbackScale] } : { scale: 'auto' };
|
|
99
100
|
if (!fallbackScale && tokenFiles.length > 0) {
|
|
100
101
|
ruleOptions.scaleSources = tokenFiles.map(toPosix);
|
|
101
102
|
}
|
|
102
103
|
return {
|
|
103
104
|
extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
|
|
105
|
+
// postcss-scss also parses plain CSS, so a mixed project needs only this.
|
|
106
|
+
...(scss ? { customSyntax: 'postcss-scss' } : {}),
|
|
104
107
|
...(nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
|
|
105
108
|
rules: {
|
|
106
109
|
'rhythmguard/use-scale': [true, ruleOptions],
|
|
@@ -108,17 +111,28 @@ function suggestedStylelintConfig({ fallbackScale = null, nextjs = false, profil
|
|
|
108
111
|
};
|
|
109
112
|
}
|
|
110
113
|
|
|
111
|
-
|
|
114
|
+
/**
|
|
115
|
+
* The eslint.config.js block. It imports the package the printed install line
|
|
116
|
+
* installs. With TypeScript files it lints .ts and .tsx through typescript-eslint's
|
|
117
|
+
* parser: the default parser reads no TSX, so a JS-only block linted nothing (dx-04).
|
|
118
|
+
*/
|
|
119
|
+
// Written this way so the snippet's import lines are not read as imports of this file.
|
|
120
|
+
const quoted = (name) => `'${name}'`;
|
|
121
|
+
|
|
122
|
+
function eslintSnippet(scaleValues, { typescript = false } = {}) {
|
|
112
123
|
const scale = scaleValues.filter((value) => typeof value === 'number').join(', ');
|
|
113
124
|
return [
|
|
114
125
|
"// eslint.config.js",
|
|
115
|
-
|
|
126
|
+
`import rhythmguard from ${quoted('eslint-plugin-rhythmguard')};`,
|
|
127
|
+
...(typescript ? [`import tseslint from ${quoted('typescript-eslint')};`] : []),
|
|
116
128
|
'',
|
|
117
129
|
'export default [',
|
|
118
130
|
' {',
|
|
119
131
|
// Without `files` and JSX parsing, a flat config lints no .jsx at all (#243).
|
|
120
|
-
" files: ['**/*.{js,jsx,mjs,cjs}'],",
|
|
121
|
-
|
|
132
|
+
typescript ? " files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}']," : " files: ['**/*.{js,jsx,mjs,cjs}'],",
|
|
133
|
+
typescript
|
|
134
|
+
? ' languageOptions: { parser: tseslint.parser, parserOptions: { ecmaFeatures: { jsx: true } } },'
|
|
135
|
+
: ' languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },',
|
|
122
136
|
" plugins: { 'rhythmguard-tailwind': rhythmguard },",
|
|
123
137
|
` rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['warn', { scale: [${scale}] }] },`,
|
|
124
138
|
' },',
|
|
@@ -126,20 +140,19 @@ function eslintSnippet(scaleValues) {
|
|
|
126
140
|
].join('\n');
|
|
127
141
|
}
|
|
128
142
|
|
|
129
|
-
function shellQuote(value) {
|
|
130
|
-
return /^[\w./@%+=:,-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
|
|
131
|
-
}
|
|
132
|
-
|
|
133
143
|
/**
|
|
134
144
|
* The commands to run next. The audit commands pass what quickstart passed,
|
|
135
145
|
* `--scale auto` and the token files it read, so they report the same scale
|
|
136
146
|
* and the same findings; `audit .` alone would use the default scale (#287).
|
|
137
147
|
*/
|
|
138
|
-
function nextCommands(tokenSources) {
|
|
139
|
-
const audit =
|
|
148
|
+
function nextCommands(tokenSources, { eslint = false, glob = '**/*.css', stylelint = true } = {}) {
|
|
149
|
+
const audit = auditCommand({ dir: '.', scale: 'auto', tokenSources: tokenSources.map(toPosix) });
|
|
140
150
|
// Each note on its own line above its command, so a long command copies whole.
|
|
141
151
|
return [
|
|
142
|
-
['Lint with the config above:',
|
|
152
|
+
...(stylelint ? [['Lint stylesheets with the config above:', `npx stylelint "${glob}"`]] : []),
|
|
153
|
+
...(eslint ? [['Lint class strings with the ESLint config above:', 'npx eslint .']] : []),
|
|
154
|
+
// Snapping a value can move layout: decide per value, then rewrite (dx-11).
|
|
155
|
+
['Propose one decision per off-scale value, before changing any:', `${audit} --plan`],
|
|
143
156
|
['PR-ready report:', `${audit} --format markdown`],
|
|
144
157
|
['Then gate only new drift in CI, with the same flags:', `${audit} --write-baseline`],
|
|
145
158
|
['Check the setup:', 'npx rhythmguard doctor'],
|
|
@@ -201,10 +214,12 @@ async function run() {
|
|
|
201
214
|
}
|
|
202
215
|
|
|
203
216
|
const scanned = report.scanned || {};
|
|
204
|
-
const skippedStylesheets = (scanned.scssSkipped || 0) + (scanned.stylelintIgnored || 0) + (scanned.nonAuthoredSkipped || 0);
|
|
217
|
+
const skippedStylesheets = (scanned.scssSkipped || 0) + (scanned.stylelintIgnored || 0) + (scanned.nonAuthoredSkipped || 0) + (scanned.stylelintMissing || 0);
|
|
218
|
+
// An ESLint-only project: class strings were audited, stylesheets were not.
|
|
219
|
+
const withoutStylelint = (scanned.stylelintMissing || 0) > 0;
|
|
205
220
|
if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0 && skippedStylesheets === 0) {
|
|
206
221
|
out.push(' No CSS files found here. Run from your project root, or audit a directory directly:');
|
|
207
|
-
out.push(' npx rhythmguard audit
|
|
222
|
+
out.push(' npx rhythmguard audit <directory>', '');
|
|
208
223
|
process.stdout.write(`${out.join('\n')}\n`);
|
|
209
224
|
return;
|
|
210
225
|
}
|
|
@@ -228,6 +243,7 @@ async function run() {
|
|
|
228
243
|
out.push(` Template files ${report.templateFilesScanned}`);
|
|
229
244
|
if (skippedStylesheets > 0) {
|
|
230
245
|
const reasons = [
|
|
246
|
+
...(withoutStylelint ? [`${scanned.stylelintMissing} because Stylelint is not installed`] : []),
|
|
231
247
|
...(scanned.scssSkipped > 0 ? [`${scanned.scssSkipped} SCSS without postcss-scss`] : []),
|
|
232
248
|
...(scanned.stylelintIgnored > 0 ? [`${scanned.stylelintIgnored} in .stylelintignore`] : []),
|
|
233
249
|
...(scanned.nonAuthoredSkipped > 0 ? [`${scanned.nonAuthoredSkipped} vendored, minified or built`] : []),
|
|
@@ -256,21 +272,45 @@ async function run() {
|
|
|
256
272
|
out.push('');
|
|
257
273
|
|
|
258
274
|
const profile = stack.tailwind ? 'tailwind' : 'recommended';
|
|
259
|
-
|
|
260
|
-
const
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
out.push(
|
|
267
|
-
out.push(
|
|
268
|
-
out.push('
|
|
275
|
+
const files = report.files || { cssFiles: [], templateFiles: [] };
|
|
276
|
+
const scss = files.cssFiles.some((file) => file.endsWith('.scss'));
|
|
277
|
+
const templateExtensions = new Set(files.templateFiles.map((file) => path.extname(file)));
|
|
278
|
+
const typescript = templateExtensions.has('.ts') || templateExtensions.has('.tsx');
|
|
279
|
+
const otherTemplates = ['.vue', '.svelte', '.astro'].filter((extension) => templateExtensions.has(extension));
|
|
280
|
+
const glob = lintGlob(cwd, files.cssFiles);
|
|
281
|
+
const printStylelint = () => {
|
|
282
|
+
out.push(withoutStylelint ? ' To audit your stylesheets too, install Stylelint and the plugin:' : ' Install:', '');
|
|
283
|
+
out.push(` ${stylelintInstallLine({ scss, tailwindConfig: profile === 'tailwind' })}`, '');
|
|
284
|
+
out.push(` ${withoutStylelint ? 'then paste' : 'Then paste'} this into .stylelintrc.json${stack.hasExistingConfig ? ' (merge with your existing config)' : ''}:`, '');
|
|
285
|
+
const fallbackScale = scale.source === 'fallback' ? scale.values : null;
|
|
286
|
+
out.push(JSON.stringify(suggestedStylelintConfig({ fallbackScale, nextjs: stack.nextjs, profile, scss, tokenFiles }), null, 2).replace(/^/gm, ' '));
|
|
269
287
|
out.push('');
|
|
288
|
+
};
|
|
289
|
+
const printEslint = () => {
|
|
290
|
+
out.push(' Tailwind class strings need the ESLint companion. Install:', '');
|
|
291
|
+
out.push(` ${eslintInstallLine({ typescript })}`, '');
|
|
292
|
+
out.push(' Then paste this into eslint.config.js:', '');
|
|
293
|
+
out.push(eslintSnippet(scale.values, { typescript }).replace(/^/gm, ' '));
|
|
294
|
+
if (otherTemplates.length > 0) {
|
|
295
|
+
out.push('', ` ${otherTemplates.join(', ')} files need their parser in a block of their own; see the`);
|
|
296
|
+
out.push(' eslint-plugin-rhythmguard README, "Other file types".');
|
|
297
|
+
}
|
|
298
|
+
out.push('');
|
|
299
|
+
};
|
|
300
|
+
|
|
301
|
+
// Without Stylelint the class strings are what was audited, so their config comes first.
|
|
302
|
+
if (stack.tailwind && withoutStylelint) {
|
|
303
|
+
printEslint();
|
|
304
|
+
printStylelint();
|
|
305
|
+
} else {
|
|
306
|
+
printStylelint();
|
|
307
|
+
if (stack.tailwind) {
|
|
308
|
+
printEslint();
|
|
309
|
+
}
|
|
270
310
|
}
|
|
271
311
|
|
|
272
312
|
out.push(' Next');
|
|
273
|
-
out.push(...nextCommands(auditTokenSources).map((line) => ` ${line}`));
|
|
313
|
+
out.push(...nextCommands(auditTokenSources, { eslint: stack.tailwind, glob, stylelint: !withoutStylelint }).map((line) => ` ${line}`));
|
|
274
314
|
out.push('');
|
|
275
315
|
|
|
276
316
|
process.stdout.write(`${out.join('\n')}\n`);
|
package/src/core/token-map.js
CHANGED
|
@@ -3,7 +3,6 @@
|
|
|
3
3
|
const { readJsonFile } = require('./json');
|
|
4
4
|
const { parseTokenValueLength } = require('./token-sources');
|
|
5
5
|
|
|
6
|
-
const { spawnSync } = require('node:child_process');
|
|
7
6
|
const fs = require('node:fs');
|
|
8
7
|
const path = require('node:path');
|
|
9
8
|
const {
|
|
@@ -288,70 +287,15 @@ function loadTailwindSpacingFromRequire(resolvedPath) {
|
|
|
288
287
|
}
|
|
289
288
|
}
|
|
290
289
|
|
|
291
|
-
function loadTailwindSpacingFromDynamicImport(resolvedPath) {
|
|
292
|
-
const script = [
|
|
293
|
-
'const { pathToFileURL } = require("node:url");',
|
|
294
|
-
'(async () => {',
|
|
295
|
-
' try {',
|
|
296
|
-
' const configPath = process.argv[1];',
|
|
297
|
-
' const loaded = await import(pathToFileURL(configPath).href);',
|
|
298
|
-
' const config = loaded && typeof loaded.default === "object" ? loaded.default : loaded;',
|
|
299
|
-
' if (!config || typeof config !== "object" || Array.isArray(config)) {',
|
|
300
|
-
' process.stdout.write("{}");',
|
|
301
|
-
' return;',
|
|
302
|
-
' }',
|
|
303
|
-
' const theme = config.theme && typeof config.theme === "object" && !Array.isArray(config.theme)',
|
|
304
|
-
' ? config.theme',
|
|
305
|
-
' : null;',
|
|
306
|
-
' if (!theme) {',
|
|
307
|
-
' process.stdout.write("{}");',
|
|
308
|
-
' return;',
|
|
309
|
-
' }',
|
|
310
|
-
' const spacing = theme.spacing && typeof theme.spacing === "object" && !Array.isArray(theme.spacing)',
|
|
311
|
-
' ? theme.spacing',
|
|
312
|
-
' : {};',
|
|
313
|
-
' const extendSpacing = theme.extend && typeof theme.extend === "object" && !Array.isArray(theme.extend) &&',
|
|
314
|
-
' theme.extend.spacing && typeof theme.extend.spacing === "object" && !Array.isArray(theme.extend.spacing)',
|
|
315
|
-
' ? theme.extend.spacing',
|
|
316
|
-
' : {};',
|
|
317
|
-
' process.stdout.write(JSON.stringify({ ...spacing, ...extendSpacing }));',
|
|
318
|
-
' } catch {',
|
|
319
|
-
' process.exit(1);',
|
|
320
|
-
' }',
|
|
321
|
-
'})();',
|
|
322
|
-
].join('\n');
|
|
323
|
-
|
|
324
|
-
const child = spawnSync(process.execPath, ['-e', script, resolvedPath], {
|
|
325
|
-
encoding: 'utf8',
|
|
326
|
-
timeout: 5000,
|
|
327
|
-
});
|
|
328
|
-
|
|
329
|
-
if (child.error || child.status !== 0) {
|
|
330
|
-
return null;
|
|
331
|
-
}
|
|
332
|
-
|
|
333
|
-
if (typeof child.stdout !== 'string' || child.stdout.trim() === '') {
|
|
334
|
-
return null;
|
|
335
|
-
}
|
|
336
|
-
|
|
337
|
-
try {
|
|
338
|
-
const parsed = JSON.parse(child.stdout);
|
|
339
|
-
return isPlainObject(parsed)
|
|
340
|
-
? parsed
|
|
341
|
-
: null;
|
|
342
|
-
} catch {
|
|
343
|
-
return null;
|
|
344
|
-
}
|
|
345
|
-
}
|
|
346
|
-
|
|
347
290
|
function loadTailwindSpacing(resolvedPath) {
|
|
348
291
|
if (tailwindSpacingCache.has(resolvedPath)) {
|
|
349
292
|
return tailwindSpacingCache.get(resolvedPath);
|
|
350
293
|
}
|
|
351
294
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
295
|
+
// require() loads CommonJS and ES module configs alike on every supported Node
|
|
296
|
+
// (require(esm) is on from 20.19). A config that uses top-level await cannot be
|
|
297
|
+
// required and is not read; point scaleSources at the built CSS instead.
|
|
298
|
+
const spacing = loadTailwindSpacingFromRequire(resolvedPath);
|
|
355
299
|
|
|
356
300
|
tailwindSpacingCache.set(resolvedPath, spacing);
|
|
357
301
|
return spacing;
|
|
@@ -109,6 +109,14 @@
|
|
|
109
109
|
],
|
|
110
110
|
"tokenPattern": "^--wpds-dimension-(?:gap|padding)-",
|
|
111
111
|
"note": "--wpds-dimension-gap-* and --wpds-dimension-padding-* in px; size and surface tokens are not spacing"
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"name": "@wikimedia/codex-design-tokens",
|
|
115
|
+
"files": [
|
|
116
|
+
"dist/theme-wikimedia-ui.css"
|
|
117
|
+
],
|
|
118
|
+
"tokenPattern": "^--spacing-\\d+$",
|
|
119
|
+
"note": "Codex ladder --spacing-0..400 (0 to 64px); the named --spacing-* tokens are computed component values"
|
|
112
120
|
}
|
|
113
121
|
]
|
|
114
122
|
}
|