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.
@@ -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
- function renderText(report) {
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 (report.totalWarnings === 0 && parseErrors(report).length > 0) {
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
- lines.push(' → Run "npx stylelint --fix" for CSS declaration fixes.');
81
- lines.push(' → Use "npx rhythmguard audit ./src --format markdown" for PR/design review.');
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,
@@ -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 says what to install instead of failing on a module path.
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
- 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
- );
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/copilot-instructions.md', target: path.join('.github', 'copilot-instructions.md'), mode: 'append' },
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. Claude Code and Cursor files are owned by Rhythmguard and
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 { mode, source, target } = AGENT_TARGETS[name];
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
- if (mode === 'append' && fs.existsSync(targetPath)) {
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(` npx stylelint "src/**/*.css"\n\n`);
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
  }
@@ -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
- function eslintSnippet(scaleValues) {
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
- "import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';",
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
- ' languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },',
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 = ['npx rhythmguard audit .', '--scale auto', ...tokenSources.map((file) => `--token-source ${shellQuote(toPosix(file))}`)].join(' ');
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:', 'npx stylelint "**/*.css"'],
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 ./src', '');
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
- out.push(` Paste this into .stylelintrc.json${stack.hasExistingConfig ? ' (merge with your existing config)' : ''}:`, '');
260
- const fallbackScale = scale.source === 'fallback' ? scale.values : null;
261
- out.push(JSON.stringify(suggestedStylelintConfig({ fallbackScale, nextjs: stack.nextjs, profile, tokenFiles }), null, 2).replace(/^/gm, ' '));
262
- out.push('');
263
-
264
- if (stack.tailwind) {
265
- out.push(' Tailwind class strings need the ESLint companion. Paste this into eslint.config.js:', '');
266
- out.push(eslintSnippet(scale.values).replace(/^/gm, ' '));
267
- out.push('', ' TypeScript, Vue, Svelte and Astro files need their parser in a block of their own; see the');
268
- out.push(' eslint-plugin-rhythmguard README, "Other file types".');
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`);
@@ -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
- const spacing =
353
- loadTailwindSpacingFromRequire(resolvedPath) ||
354
- loadTailwindSpacingFromDynamicImport(resolvedPath);
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
  }