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
@@ -0,0 +1,210 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * What the quickstart prints and `init` writes, computed once (dx-02, dx-06,
5
+ * tf-06): the audit's own scale inference, the Stylelint config that
6
+ * reproduces it, and the `.rhythmguardrc.json` that makes a bare
7
+ * `rhythmguard audit .` (and an agent) use the same scale.
8
+ */
9
+ const fs = require('node:fs');
10
+ const path = require('node:path');
11
+
12
+ const { createAuditReport } = require('../audit/report');
13
+
14
+ // tokens.json, *.tokens.json, *-tokens.json and the same as CSS (tf-12).
15
+ const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.(json|css)$/i;
16
+ // Style Dictionary's CSS output: build/css/variables.css and dist/css/variables.css.
17
+ const BUILT_VARIABLES = /^variables\.css$/i;
18
+ const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens'), 'src', 'styles', path.join('src', 'styles')];
19
+ const BUILT_DIRS = [path.join('build', 'css'), path.join('dist', 'css')];
20
+ const TAILWIND_CONFIG_FILES = ['tailwind.config.js', 'tailwind.config.cjs', 'tailwind.config.mjs', 'tailwind.config.ts'];
21
+ const RC_FILE = '.rhythmguardrc.json';
22
+
23
+ function readPackage(cwd) {
24
+ try {
25
+ return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
26
+ } catch {
27
+ // No readable package.json: no dependencies to read.
28
+ return {};
29
+ }
30
+ }
31
+
32
+ function tailwindMajor(pkg) {
33
+ const deps = { ...pkg.dependencies, ...pkg.devDependencies };
34
+ if (deps['@tailwindcss/postcss'] || deps['@tailwindcss/vite']) {
35
+ return 4;
36
+ }
37
+ const spec = deps.tailwindcss;
38
+ if (!spec) {
39
+ return null;
40
+ }
41
+ const match = String(spec).match(/(\d+)/);
42
+ return match ? Number(match[1]) : null;
43
+ }
44
+
45
+ function findTokenFiles(cwd) {
46
+ const found = new Set();
47
+ const consider = (dir, pattern) => {
48
+ let entries;
49
+ try {
50
+ entries = fs.readdirSync(dir, { withFileTypes: true });
51
+ } catch {
52
+ // A directory that does not exist holds no token files.
53
+ return;
54
+ }
55
+ for (const entry of entries) {
56
+ if (entry.isFile() && pattern.test(entry.name)) {
57
+ found.add(path.relative(cwd, path.join(dir, entry.name)));
58
+ }
59
+ }
60
+ };
61
+ consider(cwd, TOKEN_FILE_PATTERN);
62
+ for (const sub of TOKEN_DIRS) {
63
+ consider(path.join(cwd, sub), TOKEN_FILE_PATTERN);
64
+ }
65
+ for (const sub of BUILT_DIRS) {
66
+ consider(path.join(cwd, sub), BUILT_VARIABLES);
67
+ }
68
+ return Array.from(found).sort();
69
+ }
70
+
71
+ /** The Tailwind config at the project root, relative to it, or null. Found, never loaded. */
72
+ function findTailwindConfig(cwd) {
73
+ return TAILWIND_CONFIG_FILES.find((file) => fs.existsSync(path.join(cwd, file))) || null;
74
+ }
75
+
76
+ function toPosix(relativePath) {
77
+ return relativePath.startsWith('./') ? relativePath : `./${relativePath.split(path.sep).join('/')}`;
78
+ }
79
+
80
+ /**
81
+ * Run the audit's scale inference on `cwd`, as the quickstart and `init` both
82
+ * do. A Tailwind v3 config is found but not loaded: loading it runs it, which
83
+ * Rhythmguard does only when asked (SECURITY.md). The config this returns
84
+ * names it, so Stylelint reads it once the user pastes or writes that config.
85
+ */
86
+ async function inferFirstRun({ cwd = process.cwd(), stack }) {
87
+ const pkg = readPackage(cwd);
88
+ const twMajor = stack.tailwind ? tailwindMajor(pkg) : null;
89
+ const tokenFiles = findTokenFiles(cwd);
90
+ const rcPresent = fs.existsSync(path.join(cwd, RC_FILE));
91
+ const tailwindConfig = stack.tailwind && twMajor !== null && twMajor < 4 ? findTailwindConfig(cwd) : null;
92
+ // With an rc file its token sources are used; otherwise the token files found here.
93
+ const auditTokenSources = rcPresent ? [] : tokenFiles;
94
+ const report = await createAuditReport({
95
+ dir: path.relative(process.cwd(), cwd) || '.',
96
+ scale: 'auto',
97
+ ...(auditTokenSources.length > 0 ? { tokenSources: auditTokenSources.map((file) => path.relative(process.cwd(), path.join(cwd, file))) } : {}),
98
+ });
99
+ return { auditTokenSources, rcPresent, report, tailwindConfig, tokenFiles, twMajor };
100
+ }
101
+
102
+ /**
103
+ * The files `scaleSources` should name so Stylelint infers the audit's scale
104
+ * on every file, not only on the one that declares the tokens (dx-02): the
105
+ * token files the audit read, or the stylesheets it took the tokens from.
106
+ */
107
+ function scaleSourcesFor(scale, tokenFiles) {
108
+ if (scale.source === 'token-sources') {
109
+ return tokenFiles.length > 0 ? tokenFiles.map(toPosix) : scale.files.map(toPosix);
110
+ }
111
+ if (scale.source === 'scanned-css') {
112
+ return scale.files.map(toPosix);
113
+ }
114
+ return [];
115
+ }
116
+
117
+ /**
118
+ * The Stylelint config that reproduces the audit. With a scale inferred from
119
+ * tokens it is `scale: "auto"` pointed at the same files. With a Tailwind v3
120
+ * config it is `scale: "auto"` with `tailwindConfigPath`. When the audit fell
121
+ * back to the default scale, that scale is written out: `configs/tailwind`
122
+ * would otherwise fall back to Tailwind's ladder, and the pasted config would
123
+ * not reproduce this report (#246).
124
+ */
125
+ function stylelintConfigFor({ nextjs = false, profile, scale, scss = false, tailwindConfig = null, tokenFiles = [] }) {
126
+ const sources = scaleSourcesFor(scale, tokenFiles);
127
+ let ruleOptions = null;
128
+ if (tailwindConfig && sources.length === 0) {
129
+ ruleOptions = { scale: 'auto', tailwindConfigPath: toPosix(tailwindConfig) };
130
+ } else if (scale.source === 'fallback' && tokenFiles.length > 0) {
131
+ // Token files that gave no scale: point at them anyway, so every lint
132
+ // names why they were not read until they are fixed (tf-12). The fallback
133
+ // is the profile's, as in the audit.
134
+ ruleOptions = { scale: 'auto', scaleSources: tokenFiles.map(toPosix), ...(profile === 'tailwind' ? { preset: 'tailwind' } : {}) };
135
+ } else if (scale.source === 'explicit') {
136
+ ruleOptions = { scale: [...scale.values] };
137
+ } else if (scale.source !== 'fallback' && scale.source !== 'default') {
138
+ ruleOptions = { scale: 'auto', ...(sources.length > 0 ? { scaleSources: sources } : {}) };
139
+ }
140
+ // On a fallback the profile's own scale is the audit's (DEFAULT_SCALE for
141
+ // recommended, Tailwind's ladder for tailwind), so no rule is written.
142
+ return {
143
+ extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
144
+ // postcss-scss also parses plain CSS, so a mixed project needs only this.
145
+ ...(scss ? { customSyntax: 'postcss-scss' } : {}),
146
+ ...(nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
147
+ ...(ruleOptions ? { rules: { 'rhythmguard/use-scale': [true, ruleOptions] } } : {}),
148
+ };
149
+ }
150
+
151
+ /**
152
+ * The `.rhythmguardrc.json` that makes a bare `npx rhythmguard audit .` use
153
+ * the scale this run found (ai-01): `scale: "auto"` with the token files.
154
+ * Read by the audit and, for token sources, by the rules. It never names a
155
+ * Tailwind config: a file in the repository must not make the audit run code
156
+ * (only `--tailwind-config` on the command line does).
157
+ */
158
+ function rcFor({ tokenFiles = [] }) {
159
+ return {
160
+ audit: {
161
+ scale: 'auto',
162
+ ...(tokenFiles.length > 0 ? { tokenSources: tokenFiles.map(toPosix) } : {}),
163
+ },
164
+ };
165
+ }
166
+
167
+ /** A line diff of two texts, `-` and `+` marked, for showing what a write replaces. */
168
+ function lineDiff(before, after) {
169
+ const a = before.replace(/\n$/, '').split('\n');
170
+ const b = after.replace(/\n$/, '').split('\n');
171
+ const lengths = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
172
+ for (let i = a.length - 1; i >= 0; i -= 1) {
173
+ for (let j = b.length - 1; j >= 0; j -= 1) {
174
+ lengths[i][j] = a[i] === b[j] ? lengths[i + 1][j + 1] + 1 : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
175
+ }
176
+ }
177
+ const lines = [];
178
+ let i = 0;
179
+ let j = 0;
180
+ while (i < a.length && j < b.length) {
181
+ if (a[i] === b[j]) {
182
+ lines.push(` ${a[i]}`);
183
+ i += 1;
184
+ j += 1;
185
+ } else if (lengths[i + 1][j] >= lengths[i][j + 1]) {
186
+ lines.push(`- ${a[i]}`);
187
+ i += 1;
188
+ } else {
189
+ lines.push(`+ ${b[j]}`);
190
+ j += 1;
191
+ }
192
+ }
193
+ while (i < a.length) lines.push(`- ${a[i++]}`);
194
+ while (j < b.length) lines.push(`+ ${b[j++]}`);
195
+ return lines;
196
+ }
197
+
198
+ module.exports = {
199
+ RC_FILE,
200
+ findTailwindConfig,
201
+ findTokenFiles,
202
+ inferFirstRun,
203
+ lineDiff,
204
+ rcFor,
205
+ readPackage,
206
+ scaleSourcesFor,
207
+ stylelintConfigFor,
208
+ tailwindMajor,
209
+ toPosix,
210
+ };
package/src/cli/index.js CHANGED
@@ -9,6 +9,8 @@ the spacing scale, audits the current directory and prints a config to paste.
9
9
  Commands:
10
10
  quickstart Same as running with no command
11
11
  audit <dir> Report design-system drift across CSS and Tailwind class strings
12
+ scale [dir] Print the scale the audit checks against, its source and the
13
+ tokens that hold each step (--format json for agents)
12
14
  fix <dir> Replace one off-scale value everywhere, or execute snap decisions
13
15
  init Scaffold a Rhythmguard config for your project
14
16
  --agents <claude|cursor|copilot|all> installs the agent instruction packs instead
@@ -22,6 +24,7 @@ Examples:
22
24
  npx rhythmguard
23
25
  npx rhythmguard audit ./src
24
26
  npx rhythmguard audit ./src --format markdown
27
+ npx rhythmguard scale --scale auto --format json
25
28
  npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write
26
29
  npx rhythmguard init
27
30
  npx rhythmguard init --agents all
@@ -47,6 +50,8 @@ function main() {
47
50
  require('./quickstart').run();
48
51
  } else if (command === 'audit') {
49
52
  require('./audit').run();
53
+ } else if (command === 'scale') {
54
+ require('./scale').run();
50
55
  } else if (command === 'fix') {
51
56
  require('./fix').run();
52
57
  } else if (command === 'init') {
@@ -60,7 +65,26 @@ function main() {
60
65
  }
61
66
  }
62
67
 
63
- module.exports = { HELP, main };
68
+ /**
69
+ * The doctor's checks as a function: `runDoctor({ cwd })` resolves to typed
70
+ * checks instead of printing them (cq-11). Loaded on first call, so the CLI
71
+ * does not pay for it on other commands.
72
+ */
73
+ function runDoctor(options) {
74
+ return require('./doctor').runDoctor(options);
75
+ }
76
+
77
+ /** The text `rhythmguard doctor` prints for a runDoctor result. */
78
+ function formatDoctorReport(result) {
79
+ return require('./doctor').formatDoctorReport(result);
80
+ }
81
+
82
+ /** A short summary of a runDoctor result (or its checks) for another command to print. */
83
+ function doctorSummary(resultOrChecks) {
84
+ return require('./doctor').doctorSummary(resultOrChecks);
85
+ }
86
+
87
+ module.exports = { HELP, doctorSummary, formatDoctorReport, main, runDoctor };
64
88
 
65
89
  if (require.main === module) {
66
90
  main();
package/src/cli/index.mjs CHANGED
@@ -6,3 +6,6 @@ const cli = require('./index.js');
6
6
  export default cli;
7
7
  export const HELP = cli.HELP;
8
8
  export const main = cli.main;
9
+ export const runDoctor = cli.runDoctor;
10
+ export const formatDoctorReport = cli.formatDoctorReport;
11
+ export const doctorSummary = cli.doctorSummary;
package/src/cli/init.js CHANGED
@@ -2,8 +2,12 @@
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');
5
7
  const readline = require('node:readline');
6
8
 
9
+ const { RC_FILE, inferFirstRun, lineDiff, rcFor, stylelintConfigFor } = require('./first-run');
10
+
7
11
  function createPrompter() {
8
12
  if (!process.stdin.isTTY) {
9
13
  const answers = fs.readFileSync(0, 'utf8').split(/\r?\n/);
@@ -124,6 +128,7 @@ function findActiveStylelintConfig(cwd = process.cwd()) {
124
128
  try {
125
129
  content = fs.readFileSync(path.join(cwd, file), 'utf8');
126
130
  } catch {
131
+ // Not in this directory: Stylelint skips it too.
127
132
  continue;
128
133
  }
129
134
 
@@ -164,6 +169,7 @@ function configKind(file, content) {
164
169
  JSON.parse(content);
165
170
  return 'json';
166
171
  } catch {
172
+ // Not JSON: a .stylelintrc holds YAML.
167
173
  return 'yaml';
168
174
  }
169
175
  }
@@ -176,8 +182,11 @@ function configSnippet(kind, config) {
176
182
  return JSON.stringify({ stylelint: config }, null, 2).split('\n').slice(1, -1).map((line) => line.slice(2)).join('\n');
177
183
  }
178
184
  if (kind === 'yaml') {
185
+ // A list of strings as a YAML list; anything else in JSON flow style, which is YAML too.
179
186
  return Object.entries(config)
180
- .map(([key, values]) => `${key}:\n${values.map((value) => ` - ${JSON.stringify(value)}`).join('\n')}`)
187
+ .map(([key, values]) => (Array.isArray(values) && values.every((value) => typeof value === 'string')
188
+ ? `${key}:\n${values.map((value) => ` - ${JSON.stringify(value)}`).join('\n')}`
189
+ : `${key}: ${JSON.stringify(values)}`))
181
190
  .join('\n');
182
191
  }
183
192
  return Object.entries(config)
@@ -195,7 +204,7 @@ function selectProfile(stack) {
195
204
  const AGENT_TARGETS = {
196
205
  claude: { source: 'claude-code/SKILL.md', target: path.join('.claude', 'skills', 'rhythmguard', 'SKILL.md'), mode: 'write' },
197
206
  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' },
207
+ copilot: { source: 'copilot/rhythmguard.instructions.md', target: path.join('.github', 'instructions', 'rhythmguard.instructions.md'), mode: 'write' },
199
208
  };
200
209
  const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
201
210
  const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
@@ -238,11 +247,31 @@ function parseInitArgs(argv) {
238
247
  return parsed;
239
248
  }
240
249
 
250
+ /**
251
+ * Up to 3.18 the Copilot pack was appended to .github/copilot-instructions.md
252
+ * between markers. It now has its own path-specific file, so the old block,
253
+ * which this command wrote and owns, is taken out to leave one copy.
254
+ */
255
+ function removeLegacyCopilotBlock(cwd) {
256
+ const legacy = path.join('.github', 'copilot-instructions.md');
257
+ const legacyPath = path.join(cwd, legacy);
258
+ if (!fs.existsSync(legacyPath)) return null;
259
+ const existing = fs.readFileSync(legacyPath, 'utf8');
260
+ const start = existing.indexOf(AGENT_BLOCK_START);
261
+ const end = existing.indexOf(AGENT_BLOCK_END);
262
+ if (start === -1 || end === -1 || end < start) return null;
263
+ const next = `${existing.slice(0, start).trimEnd()}\n${existing.slice(end + AGENT_BLOCK_END.length).replace(/^\n+/, '\n')}`.replace(/^\n+/, '');
264
+ if (next.trim() === '') {
265
+ fs.rmSync(legacyPath);
266
+ } else {
267
+ fs.writeFileSync(legacyPath, next.endsWith('\n') ? next : `${next}\n`);
268
+ }
269
+ return legacy;
270
+ }
271
+
241
272
  /**
242
273
  * 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.
274
+ * agent reads. Every target is a file Rhythmguard owns, overwritten on rerun.
246
275
  */
247
276
  function installAgents(selection, cwd = process.cwd()) {
248
277
  const names = selection === 'all' ? Object.keys(AGENT_TARGETS) : [selection];
@@ -254,24 +283,17 @@ function installAgents(selection, cwd = process.cwd()) {
254
283
  const packsDir = path.join(__dirname, '..', '..', 'agents');
255
284
  const written = [];
256
285
  for (const name of names) {
257
- const { mode, source, target } = AGENT_TARGETS[name];
286
+ const { source, target } = AGENT_TARGETS[name];
258
287
  const content = fs.readFileSync(path.join(packsDir, source), 'utf8');
259
288
  const targetPath = path.join(cwd, target);
260
289
  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
261
290
 
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
- }
291
+ fs.writeFileSync(targetPath, content);
274
292
  written.push(target);
293
+ if (name === 'copilot') {
294
+ const moved = removeLegacyCopilotBlock(cwd);
295
+ if (moved) written.push(`${moved} (the block an older version appended there was removed)`);
296
+ }
275
297
  }
276
298
  return written;
277
299
  }
@@ -324,11 +346,16 @@ async function run() {
324
346
  }
325
347
 
326
348
  const profile = selectProfile(stack);
327
- const config = {
328
- extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
329
- // Next.js build output is generated CSS; never lint it.
330
- ...(stack.nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
331
- };
349
+ // The quickstart's inference: init writes exactly the config the quickstart
350
+ // pastes, scale or scaleSources included, so the two never disagree (dx-06).
351
+ const inferred = await inferFirstRun({ cwd: process.cwd(), stack });
352
+ const scale = inferred.report.scale;
353
+ // The stylesheets here decide the glob, and whether SCSS needs its syntax (dx-05, dx-10).
354
+ const stylesheets = (inferred.report.files || { cssFiles: [] }).cssFiles;
355
+ const scss = stylesheets.some((file) => file.endsWith('.scss'));
356
+ // Next.js build output is generated CSS; never lint it.
357
+ const config = stylelintConfigFor({ nextjs: stack.nextjs, profile, scale, scss, tailwindConfig: inferred.tailwindConfig, tokenFiles: inferred.tokenFiles });
358
+ process.stdout.write(`Scale: ${scale.values.join(', ')} (${scale.source}${scale.files && scale.files.length > 0 ? `: ${scale.files.slice(0, 3).join(', ')}` : ''})\n`);
332
359
 
333
360
  // A .stylelintrc.json next to the config Stylelint actually loads is either
334
361
  // never read (package.json, a YAML .stylelintrc) or silently takes over
@@ -348,9 +375,20 @@ async function run() {
348
375
  return;
349
376
  }
350
377
 
351
- // Warn about existing config
378
+ const nextText = JSON.stringify(config, null, 2) + '\n';
379
+
380
+ // Warn about existing config, and show what the write replaces (dx-06).
352
381
  if (stack.hasExistingConfig) {
353
382
  process.stdout.write('\n⚠ Existing Stylelint config found.\n');
383
+ let current = '';
384
+ try {
385
+ current = fs.readFileSync(path.join(process.cwd(), active.file), 'utf8');
386
+ } catch {
387
+ // Not readable: nothing to compare.
388
+ }
389
+ if (current) {
390
+ process.stdout.write(`\nChanges to ${active.file}:\n\n${lineDiff(current, nextText).map((line) => ` ${line}`).join('\n')}\n\n`);
391
+ }
354
392
  const answer = await prompter.ask('Overwrite? (y/n) ');
355
393
  if (answer !== 'y' && answer !== 'yes') {
356
394
  process.stdout.write('Aborted.\n');
@@ -368,11 +406,22 @@ async function run() {
368
406
  }
369
407
 
370
408
  const configPath = path.join(process.cwd(), targetFile);
371
- fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
409
+ fs.writeFileSync(configPath, nextText);
372
410
 
373
411
  process.stdout.write(`\n✓ Wrote ${configPath}\n`);
412
+
413
+ // The rc makes a bare `npx rhythmguard audit .` (CI, an agent) use this scale (ai-01).
414
+ if (!inferred.rcPresent) {
415
+ const rcAnswer = await prompter.ask(`Write ${RC_FILE} so \`npx rhythmguard audit .\` uses the same scale? (y/n) `);
416
+ if (rcAnswer === 'y' || rcAnswer === 'yes') {
417
+ const rcPath = path.join(process.cwd(), RC_FILE);
418
+ fs.writeFileSync(rcPath, JSON.stringify(rcFor({ tailwindConfig: inferred.tailwindConfig, tokenFiles: inferred.tokenFiles }), null, 2) + '\n');
419
+ process.stdout.write(`✓ Wrote ${rcPath}\n`);
420
+ }
421
+ }
374
422
  process.stdout.write(`\nNext steps:\n`);
375
- process.stdout.write(` npx stylelint "src/**/*.css"\n\n`);
423
+ process.stdout.write(` ${stylelintInstallLine({ scss, tailwindConfig: profile === 'tailwind' })}\n`);
424
+ process.stdout.write(` npx stylelint "${lintGlob(process.cwd(), stylesheets)}"\n\n`);
376
425
  } finally {
377
426
  prompter.close();
378
427
  }