stylelint-plugin-rhythmguard 3.12.0 → 3.14.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 (48) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +1 -1
  3. package/package.json +23 -1
  4. package/src/audit/args.js +23 -4
  5. package/src/audit/baseline.js +15 -2
  6. package/src/audit/codemod.js +56 -5
  7. package/src/audit/config.js +2 -1
  8. package/src/audit/contract.js +3 -0
  9. package/src/audit/decisions.js +45 -16
  10. package/src/audit/render-markdown.js +22 -21
  11. package/src/audit/render-text.js +4 -0
  12. package/src/audit/render-utils.js +28 -1
  13. package/src/audit/report.js +16 -2
  14. package/src/audit/scan/files.js +139 -30
  15. package/src/audit/token-chains.js +4 -1
  16. package/src/audit/token-ladders.js +23 -2
  17. package/src/cli/doctor.js +58 -6
  18. package/src/cli/fix.js +7 -6
  19. package/src/cli/index.js +2 -2
  20. package/src/cli/init.js +41 -5
  21. package/src/cli/quickstart.js +46 -8
  22. package/src/configs/embed.js +2 -0
  23. package/src/configs/motion.js +1 -0
  24. package/src/configs/recommended.js +1 -0
  25. package/src/configs/strict.js +1 -0
  26. package/src/configs/tailwind.js +1 -0
  27. package/src/core/decisions.js +2 -1
  28. package/src/core/json.js +25 -0
  29. package/src/core/length.js +11 -0
  30. package/src/core/options.js +39 -20
  31. package/src/core/scale-inference.js +78 -23
  32. package/src/core/tailwind-class-analysis.js +3 -2
  33. package/src/core/token-map.js +2 -1
  34. package/src/core/token-sources.js +143 -14
  35. package/src/eslint/index.js +14 -8
  36. package/src/eslint/rules/tailwind-class-use-motion-scale.js +1 -0
  37. package/src/eslint/rules/tailwind-class-use-scale.js +1 -0
  38. package/src/rules/no-offscale-transform/index.js +58 -53
  39. package/src/rules/prefer-token/index.js +31 -46
  40. package/src/rules/use-motion-scale/index.js +14 -1
  41. package/src/rules/use-scale/index.js +75 -102
  42. package/src/rules/validate.js +13 -4
  43. package/types/__checks__/consumer.ts +20 -1
  44. package/types/__checks__/eslint-config.ts +8 -0
  45. package/types/__checks__/shipped-configs.ts +96 -0
  46. package/types/audit.d.ts +103 -16
  47. package/types/index.d.ts +15 -0
  48. package/types/shared.d.ts +126 -20
package/src/cli/doctor.js CHANGED
@@ -5,7 +5,19 @@ const path = require('node:path');
5
5
  const { applyAuditConfig, loadAuditConfig, resolveIgnorePatterns } = require('../audit/config');
6
6
  const { createDefaultAuditOptions } = require('../audit/shared');
7
7
  const { normalizeDecisions } = require('../core/decisions');
8
- const { normalizeTokenSourceFormat } = require('../core/token-sources');
8
+ const { readJsonFile } = require('../core/json');
9
+ const { normalizeTokenSourceEntry } = require('../core/token-source-entries');
10
+ const { normalizeTokenSourceFormat, parseTokenSources } = require('../core/token-sources');
11
+
12
+ const HELP = `Usage: rhythmguard doctor
13
+
14
+ Validate the Rhythmguard setup in the current directory: Stylelint, its config,
15
+ the rules it references, .rhythmguardrc.json, token sources and the baseline.
16
+ Exits 1 when a check fails.
17
+
18
+ Options:
19
+ --help Show this help message
20
+ `;
9
21
 
10
22
  const cwd = process.cwd();
11
23
  let issues = 0;
@@ -26,6 +38,14 @@ function skip(msg) {
26
38
  process.stdout.write(`- ${msg}\n`);
27
39
  }
28
40
 
41
+ let warnings = 0;
42
+
43
+ // Worth knowing, but not a failure: the exit code does not change.
44
+ function warn(msg) {
45
+ warnings++;
46
+ process.stdout.write(`! ${msg}\n`);
47
+ }
48
+
29
49
  // Check 1: Stylelint installed
30
50
  function checkStylelint() {
31
51
  try {
@@ -218,7 +238,7 @@ function checkRhythmguardConfig() {
218
238
 
219
239
  let parsed;
220
240
  try {
221
- parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
241
+ parsed = readJsonFile(configPath);
222
242
  } catch {
223
243
  fail('.rhythmguardrc.json is not valid JSON', 'Fix or remove .rhythmguardrc.json');
224
244
  return;
@@ -302,12 +322,29 @@ function checkRhythmguardTokenSources(audit, baseDir) {
302
322
 
303
323
  if (fs.existsSync(path.resolve(baseDir, sourcePath))) {
304
324
  pass(`token source found (${sourcePath})`);
325
+ warnAboutTokenSource(source, baseDir);
305
326
  } else {
306
327
  fail(`token source not found (${sourcePath})`, 'Update audit.tokenSources or create the token file');
307
328
  }
308
329
  }
309
330
  }
310
331
 
332
+ /**
333
+ * Read a token source the way the audit reads it for the spacing scale, and
334
+ * pass on what the audit would warn about: a file that does not parse, skipped
335
+ * tokens, or no spacing tokens at all (issue #163). Warnings, not failures.
336
+ */
337
+ function warnAboutTokenSource(entry, baseDir) {
338
+ const { source } = normalizeTokenSourceEntry(entry, baseDir);
339
+ if (!source) {
340
+ return;
341
+ }
342
+ const parsed = parseTokenSources({ sources: [source], tokenKind: 'spacing', warnWhenEmpty: true });
343
+ for (const message of parsed.warnings) {
344
+ warn(message);
345
+ }
346
+ }
347
+
311
348
  function checkRhythmguardMotionConfig(audit) {
312
349
  if (audit.includeMotion === undefined) {
313
350
  skip('motion audit check skipped (not configured)');
@@ -329,7 +366,7 @@ function checkRhythmguardBaseline(audit) {
329
366
  }
330
367
 
331
368
  try {
332
- const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
369
+ const baseline = readJsonFile(baselinePath);
333
370
  if (!Array.isArray(baseline.findings)) {
334
371
  fail('baseline file does not include findings array', 'Regenerate it with rhythmguard audit --write-baseline');
335
372
  return;
@@ -341,6 +378,16 @@ function checkRhythmguardBaseline(audit) {
341
378
  }
342
379
 
343
380
  function run() {
381
+ // Doctor takes no arguments; --help prints the usage, anything else is refused (#286).
382
+ for (const arg of process.argv.slice(3)) {
383
+ if (arg === '--help' || arg === '-h') {
384
+ process.stdout.write(HELP);
385
+ return;
386
+ }
387
+ process.stderr.write(`Unknown option: ${arg}\n\n${HELP}`);
388
+ process.exit(1);
389
+ }
390
+
344
391
  process.stdout.write('\nRhythmguard Doctor\n\n');
345
392
 
346
393
  const stylelintOk = checkStylelint();
@@ -353,15 +400,20 @@ function run() {
353
400
 
354
401
  process.stdout.write('\n');
355
402
 
403
+ const warningNote = warnings > 0 ? ` (${warnings} warning${warnings === 1 ? '' : 's'})` : '';
356
404
  if (issues === 0) {
357
- process.stdout.write('All checks passed.\n\n');
405
+ process.stdout.write(`All checks passed${warningNote}.\n\n`);
358
406
  } else {
359
407
  process.stdout.write(
360
- `${issues} issue${issues === 1 ? '' : 's'} found.\n\n`,
408
+ `${issues} issue${issues === 1 ? '' : 's'} found${warningNote}.\n\n`,
361
409
  );
362
410
  }
363
411
 
364
412
  process.exit(stylelintOk && issues === 0 ? 0 : 1);
365
413
  }
366
414
 
367
- run();
415
+ module.exports = { HELP, run };
416
+
417
+ if (require.main === module) {
418
+ run();
419
+ }
package/src/cli/fix.js CHANGED
@@ -2,10 +2,11 @@
2
2
 
3
3
  const { loadRcDecisions } = require('../core/decisions');
4
4
  const { parseLengthToken, toPx } = require('../core/length');
5
- const { OPTIONS: AUDIT_OPTIONS } = require('../audit/args');
5
+ const { OPTIONS: AUDIT_OPTIONS, parseBaseFontSize } = require('../audit/args');
6
6
  const { runCodemod } = require('../audit/codemod');
7
7
  const { resolveIgnorePatterns } = require('../audit/config');
8
8
  const { normalizeCreateAuditOptions } = require('../audit/report');
9
+ const { assertDirectory } = require('../audit/scan/files');
9
10
  const { DEFAULT_IGNORE_PATH } = require('../audit/shared');
10
11
 
11
12
  // --ignore and --ignore-path are the audit's own flags, parsed by the audit's table.
@@ -62,14 +63,11 @@ function parseArgs(argv) {
62
63
  else if (arg.startsWith('--to=')) parsed.replacement = arg.slice('--to='.length);
63
64
  else if (arg === '--properties') parsed.properties = splitList(next());
64
65
  else if (arg.startsWith('--properties=')) parsed.properties = splitList(arg.slice('--properties='.length));
65
- else if (arg === '--base-font-size') parsed.baseFontSize = Number(next());
66
- else if (arg.startsWith('--base-font-size=')) parsed.baseFontSize = Number(arg.slice('--base-font-size='.length));
66
+ else if (arg === '--base-font-size') parsed.baseFontSize = parseBaseFontSize(next());
67
+ else if (arg.startsWith('--base-font-size=')) parsed.baseFontSize = parseBaseFontSize(arg.slice('--base-font-size='.length));
67
68
  else if (!arg.startsWith('-') && !parsed.dir) parsed.dir = arg;
68
69
  else throw new Error(`Unknown option: ${arg}`);
69
70
  }
70
- if (!Number.isFinite(parsed.baseFontSize) || parsed.baseFontSize <= 0) {
71
- throw new Error('--base-font-size must be a positive number.');
72
- }
73
71
  return parsed;
74
72
  }
75
73
 
@@ -138,6 +136,9 @@ function run() {
138
136
  let plan;
139
137
  let ignorePatterns;
140
138
  try {
139
+ // The same check, and the same message, as the audit: a missing path or a
140
+ // file reads "Directory not found" or "Not a directory", not a stack trace (#288).
141
+ assertDirectory(parsed.dir);
141
142
  plan = plannedReplacements(parsed);
142
143
  ignorePatterns = auditIgnorePatterns(parsed);
143
144
  } catch (error) {
package/src/cli/index.js CHANGED
@@ -15,7 +15,7 @@ Commands:
15
15
  doctor Validate your Rhythmguard setup
16
16
 
17
17
  Options:
18
- --help Show this help message
18
+ --help Show this help message; after a command, that command's help
19
19
 
20
20
  Examples:
21
21
  npx rhythmguard
@@ -45,7 +45,7 @@ function main() {
45
45
  } else if (command === 'init') {
46
46
  require('./init').run();
47
47
  } else if (command === 'doctor') {
48
- require('./doctor');
48
+ require('./doctor').run();
49
49
  } else {
50
50
  process.stderr.write(`Unknown command: ${command}\n\n`);
51
51
  process.stdout.write(HELP);
package/src/cli/init.js CHANGED
@@ -200,14 +200,39 @@ const AGENT_TARGETS = {
200
200
  const AGENT_BLOCK_START = '<!-- rhythmguard:agents:start -->';
201
201
  const AGENT_BLOCK_END = '<!-- rhythmguard:agents:end -->';
202
202
 
203
+ const HELP = `Usage: rhythmguard init [options]
204
+
205
+ Scaffold a Rhythmguard Stylelint config for the project in the current
206
+ directory. Detects Tailwind and Next.js, picks a profile and asks before it
207
+ writes. When Stylelint loads a config init cannot rewrite (package.json, YAML,
208
+ JS or TS), it prints what to add and writes nothing.
209
+
210
+ Options:
211
+ --agents [claude|cursor|copilot|all] Install the agent instruction packs instead (default: all)
212
+ --help Show this help message
213
+ `;
214
+
215
+ /**
216
+ * Init writes files, so anything it does not know stops it: `init --help`
217
+ * and a typo such as `--agnets` used to fall through to the interactive
218
+ * init and write a config (#286).
219
+ */
203
220
  function parseInitArgs(argv) {
204
- const parsed = { agents: null };
221
+ const parsed = { agents: null, help: false };
205
222
  for (let index = 0; index < argv.length; index += 1) {
206
223
  const arg = argv[index];
207
- if (arg === '--agents') {
208
- parsed.agents = String(argv[++index] || 'all').toLowerCase();
224
+ if (arg === '--help' || arg === '-h') {
225
+ parsed.help = true;
226
+ } else if (arg === '--agents') {
227
+ const next = argv[index + 1];
228
+ parsed.agents = next !== undefined && !next.startsWith('-') ? argv[++index].toLowerCase() : 'all';
209
229
  } else if (arg.startsWith('--agents=')) {
210
230
  parsed.agents = arg.slice('--agents='.length).toLowerCase();
231
+ if (!parsed.agents) {
232
+ throw new Error('Missing value for --agents.');
233
+ }
234
+ } else {
235
+ throw new Error(`Unknown option: ${arg}`);
211
236
  }
212
237
  }
213
238
  return parsed;
@@ -252,7 +277,18 @@ function installAgents(selection, cwd = process.cwd()) {
252
277
  }
253
278
 
254
279
  async function run() {
255
- const args = parseInitArgs(process.argv.slice(3));
280
+ let args;
281
+ try {
282
+ args = parseInitArgs(process.argv.slice(3));
283
+ } catch (error) {
284
+ process.stderr.write(`${error.message}\n\n${HELP}`);
285
+ process.exit(1);
286
+ }
287
+
288
+ if (args.help) {
289
+ process.stdout.write(HELP);
290
+ return;
291
+ }
256
292
 
257
293
  if (args.agents) {
258
294
  let written;
@@ -342,7 +378,7 @@ async function run() {
342
378
  }
343
379
  }
344
380
 
345
- module.exports = { AGENT_TARGETS, detect, findActiveStylelintConfig, installAgents, run, selectProfile };
381
+ module.exports = { AGENT_TARGETS, HELP, detect, findActiveStylelintConfig, installAgents, parseInitArgs, run, selectProfile };
346
382
 
347
383
  if (require.main === module) {
348
384
  run();
@@ -16,6 +16,16 @@ const { createAuditReport } = require('../audit/report');
16
16
  const { detect } = require('./init');
17
17
  const { discoverTokenPackages } = require('../core/scale-inference');
18
18
 
19
+ const HELP = `Usage: rhythmguard [quickstart]
20
+
21
+ Zero-config first run. Detects the stack and token files, infers the spacing
22
+ scale, audits the current directory, prints a config to paste and the audit
23
+ commands that reproduce its result. Never fails on findings; this is a report.
24
+
25
+ Options:
26
+ --help Show this help message
27
+ `;
28
+
19
29
  const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
20
30
  const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];
21
31
  const MAX_LISTED = 5;
@@ -116,6 +126,26 @@ function eslintSnippet(scaleValues) {
116
126
  ].join('\n');
117
127
  }
118
128
 
129
+ function shellQuote(value) {
130
+ return /^[\w./@%+=:,-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
131
+ }
132
+
133
+ /**
134
+ * The commands to run next. The audit commands pass what quickstart passed,
135
+ * `--scale auto` and the token files it read, so they report the same scale
136
+ * and the same findings; `audit .` alone would use the default scale (#287).
137
+ */
138
+ function nextCommands(tokenSources) {
139
+ const audit = ['npx rhythmguard audit .', '--scale auto', ...tokenSources.map((file) => `--token-source ${shellQuote(toPosix(file))}`)].join(' ');
140
+ // Each note on its own line above its command, so a long command copies whole.
141
+ return [
142
+ ['Lint with the config above:', 'npx stylelint "**/*.css"'],
143
+ ['PR-ready report:', `${audit} --format markdown`],
144
+ ['Then gate only new drift in CI, with the same flags:', `${audit} --write-baseline`],
145
+ ['Check the setup:', 'npx rhythmguard doctor'],
146
+ ].flatMap(([note, command]) => [note, ` ${command}`]);
147
+ }
148
+
119
149
  function describeScale(scale) {
120
150
  if (!scale) {
121
151
  return 'default';
@@ -125,6 +155,17 @@ function describeScale(scale) {
125
155
  }
126
156
 
127
157
  async function run() {
158
+ // `rhythmguard` alone has no arguments; `rhythmguard quickstart` may have --help (#286).
159
+ for (const arg of process.argv[2] === 'quickstart' ? process.argv.slice(3) : []) {
160
+ if (arg === '--help' || arg === '-h') {
161
+ process.stdout.write(HELP);
162
+ return;
163
+ }
164
+ process.stderr.write(`Unknown option: ${arg}\n\n${HELP}`);
165
+ process.exitCode = 1;
166
+ return;
167
+ }
168
+
128
169
  const cwd = process.cwd();
129
170
  const pkg = readPackage(cwd);
130
171
  const stack = detect();
@@ -144,14 +185,14 @@ async function run() {
144
185
  out.push(` .rhythmguardrc ${rcPresent ? 'present (its token sources are used)' : 'none'}`);
145
186
  out.push('');
146
187
 
188
+ // With an rc file its token sources are used; otherwise the token files found here.
189
+ const auditTokenSources = rcPresent ? [] : tokenFiles;
147
190
  let report;
148
191
  try {
149
192
  report = await createAuditReport({
150
193
  dir: '.',
151
194
  scale: 'auto',
152
- ...(tokenFiles.length > 0 && !rcPresent
153
- ? { tokenSources: tokenFiles }
154
- : {}),
195
+ ...(auditTokenSources.length > 0 ? { tokenSources: auditTokenSources } : {}),
155
196
  });
156
197
  } catch (error) {
157
198
  process.stderr.write(`Quickstart could not audit ${cwd}: ${error.message}\n`);
@@ -228,13 +269,10 @@ async function run() {
228
269
  }
229
270
 
230
271
  out.push(' Next');
231
- out.push(' npx stylelint "**/*.css" lint with the config above');
232
- out.push(' npx rhythmguard audit . --format markdown PR-ready report');
233
- out.push(' npx rhythmguard audit . --write-baseline then gate only new drift in CI');
234
- out.push(' npx rhythmguard doctor check the setup');
272
+ out.push(...nextCommands(auditTokenSources).map((line) => ` ${line}`));
235
273
  out.push('');
236
274
 
237
275
  process.stdout.write(`${out.join('\n')}\n`);
238
276
  }
239
277
 
240
- module.exports = { eslintSnippet, findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };
278
+ module.exports = { HELP, eslintSnippet, findTokenFiles, nextCommands, run, suggestedStylelintConfig, tailwindMajor };
@@ -9,6 +9,8 @@
9
9
  * No `extends`, no dependency beyond this plugin, and the shape is frozen for
10
10
  * the life of a major version so a config that embeds it never changes
11
11
  * behaviour on a minor bump.
12
+ *
13
+ * @type {import('../../types/shared').RhythmguardStylelintConfig}
12
14
  */
13
15
  module.exports = {
14
16
  plugins: ['stylelint-plugin-rhythmguard'],
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
3
4
  module.exports = {
4
5
  plugins: ['stylelint-plugin-rhythmguard'],
5
6
  rules: {
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
3
4
  module.exports = {
4
5
  plugins: ['stylelint-plugin-rhythmguard'],
5
6
  rules: {
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
3
4
  module.exports = {
4
5
  plugins: ['stylelint-plugin-rhythmguard'],
5
6
  rules: {
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ /** @type {import('../../types/shared').RhythmguardStylelintConfig} */
3
4
  module.exports = {
4
5
  extends: [
5
6
  'stylelint-config-tailwindcss',
@@ -3,6 +3,7 @@
3
3
  const fs = require('node:fs');
4
4
  const path = require('node:path');
5
5
  const { cachedByFiles } = require('./fs-cache');
6
+ const { readJsonFile } = require('./json');
6
7
  const { numbersEqual, parseLengthToken, toPx } = require('./length');
7
8
 
8
9
  /**
@@ -105,7 +106,7 @@ function loadRcDecisions(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
105
106
  }
106
107
  let config;
107
108
  try {
108
- config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
109
+ config = readJsonFile(rcPath);
109
110
  } catch {
110
111
  return [];
111
112
  }
@@ -0,0 +1,25 @@
1
+ 'use strict';
2
+
3
+ const fs = require('node:fs');
4
+
5
+ const BYTE_ORDER_MARK = /^\uFEFF/;
6
+
7
+ /** Text without a leading UTF-8 byte order mark, which some Windows editors write and JSON.parse rejects (issue #291). */
8
+ function stripBom(text) {
9
+ return String(text).replace(BYTE_ORDER_MARK, '');
10
+ }
11
+
12
+ /** JSON.parse for files people edit: a leading byte order mark is tolerated. */
13
+ function parseJson(text) {
14
+ return JSON.parse(stripBom(text));
15
+ }
16
+
17
+ function readJsonFile(file) {
18
+ return parseJson(fs.readFileSync(file, 'utf8'));
19
+ }
20
+
21
+ module.exports = {
22
+ parseJson,
23
+ readJsonFile,
24
+ stripBom,
25
+ };
@@ -224,6 +224,16 @@ function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy,
224
224
  return converted === null ? null : formatLength(converted, unit);
225
225
  }
226
226
 
227
+ /** " (16.8px)" after a bound written in rem or em, so the reader sees what was compared. */
228
+ function pxAside(value, baseFontSize) {
229
+ const parsed = parseLengthToken(value);
230
+ if (!parsed || !parsed.unit || parsed.unit === 'px' || parsed.unit === '%') {
231
+ return '';
232
+ }
233
+ const px = toPx(Math.abs(parsed.number), parsed.unit, baseFontSize);
234
+ return px === null ? '' : ` (${formatLength(parsed.number < 0 ? -px : px, 'px')})`;
235
+ }
236
+
227
237
  module.exports = {
228
238
  nearestText,
229
239
  fixedLengthValue,
@@ -236,6 +246,7 @@ module.exports = {
236
246
  normalizeScaleByUnit,
237
247
  numbersEqual,
238
248
  parseLengthToken,
249
+ pxAside,
239
250
  pxOnScale,
240
251
  toPx,
241
252
  };
@@ -92,8 +92,14 @@ function isAutoScaleLiteral(value) {
92
92
  return value === 'auto';
93
93
  }
94
94
 
95
- function isScaleEntryOrAuto(value) {
96
- return isAutoScaleLiteral(value) || isScaleEntry(value);
95
+ /** A list of scale values. An empty list checks nothing, so it is not a scale (issue #273). */
96
+ function isScaleList(value) {
97
+ return Array.isArray(value) && value.length > 0 && value.every((entry) => isScaleEntry(entry));
98
+ }
99
+
100
+ /** A name `getScalePreset` knows, built-in or community, aliases included. */
101
+ function isKnownPresetName(value) {
102
+ return typeof value === 'string' && Boolean(getScalePreset(value));
97
103
  }
98
104
 
99
105
  function isScaleSourceEntry(value) {
@@ -213,9 +219,18 @@ function isMathFunctionArgumentMap(value) {
213
219
  });
214
220
  }
215
221
 
222
+ /**
223
+ * A scale given as values, a preset name, or a { preset | scale | customScale }
224
+ * object. An empty list or an unknown preset would leave the scale empty or
225
+ * fall back to the default without a word, so neither is valid (issue #273).
226
+ */
216
227
  function isScaleOverrideEntry(value) {
217
228
  if (Array.isArray(value)) {
218
- return value.every((entry) => isScaleEntry(entry));
229
+ return isScaleList(value);
230
+ }
231
+
232
+ if (typeof value === 'string') {
233
+ return isKnownPresetName(value);
219
234
  }
220
235
 
221
236
  if (!isPlainObject(value)) {
@@ -230,18 +245,15 @@ function isScaleOverrideEntry(value) {
230
245
  return false;
231
246
  }
232
247
 
233
- if (hasPreset && !isNonEmptyString(value.preset)) {
248
+ if (hasPreset && !isKnownPresetName(value.preset)) {
234
249
  return false;
235
250
  }
236
251
 
237
- if (hasScale && (!Array.isArray(value.scale) || !value.scale.every((entry) => isScaleEntry(entry)))) {
252
+ if (hasScale && !isScaleList(value.scale)) {
238
253
  return false;
239
254
  }
240
255
 
241
- if (
242
- hasCustomScale &&
243
- (!Array.isArray(value.customScale) || !value.customScale.every((entry) => isScaleEntry(entry)))
244
- ) {
256
+ if (hasCustomScale && !isScaleList(value.customScale)) {
245
257
  return false;
246
258
  }
247
259
 
@@ -267,13 +279,7 @@ const SCALED_GROUPS = Object.freeze(['spacing', 'radius', 'size', 'typography'])
267
279
 
268
280
  /** One group's scale: values, a preset name, "auto", or a { preset | scale | customScale } object. */
269
281
  function isGroupScaleEntry(value) {
270
- if (isAutoScaleLiteral(value)) {
271
- return true;
272
- }
273
- if (typeof value === 'string') {
274
- return Boolean(getScalePreset(value));
275
- }
276
- return isScaleOverrideEntry(value);
282
+ return isAutoScaleLiteral(value) || isScaleOverrideEntry(value);
277
283
  }
278
284
 
279
285
  function isGroupScalesMap(value) {
@@ -293,7 +299,7 @@ function buildGroupScales(scales) {
293
299
  if (isAutoScaleLiteral(entry)) {
294
300
  return [group, { auto: true, scale: null }];
295
301
  }
296
- const scale = typeof entry === 'string' ? getScalePreset(entry) : resolveScaleOverride(entry);
302
+ const scale = resolveScaleOverride(entry);
297
303
  return [group, { auto: false, scale: Array.isArray(scale) ? [...scale] : null }];
298
304
  }));
299
305
  }
@@ -302,7 +308,9 @@ function buildPossibleOptionMap(schema) {
302
308
  return Object.fromEntries(
303
309
  Object.entries(schema).map(([optionName, descriptor]) => [
304
310
  optionName,
305
- [descriptor.entryValidator || VALIDATE_ALWAYS],
311
+ // A literal such as "auto" stands for the whole option; validateSecondaryOptionShapes
312
+ // rejects it inside an array (issue #273).
313
+ [...(descriptor.allowLiterals || []), descriptor.entryValidator || VALIDATE_ALWAYS],
306
314
  ]),
307
315
  );
308
316
  }
@@ -359,6 +367,12 @@ function resolveScaleOverride(override) {
359
367
  return override;
360
368
  }
361
369
 
370
+ // A preset name, as `propertyScales: { padding: "rhythmic-8" }` (issue #273).
371
+ if (typeof override === 'string') {
372
+ const preset = getScalePreset(override);
373
+ return preset ? [...preset] : null;
374
+ }
375
+
362
376
  if (!isPlainObject(override)) {
363
377
  return null;
364
378
  }
@@ -438,6 +452,7 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
438
452
  customScale: Object.freeze({
439
453
  entryValidator: isScaleEntry,
440
454
  expectsArray: true,
455
+ nonEmpty: true,
441
456
  }),
442
457
  checkMathBounds: Object.freeze({
443
458
  entryValidator: isBoolean,
@@ -467,8 +482,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
467
482
  }),
468
483
  scale: Object.freeze({
469
484
  allowLiterals: ['auto'],
470
- entryValidator: isScaleEntryOrAuto,
485
+ entryValidator: isScaleEntry,
471
486
  expectsArray: true,
487
+ nonEmpty: true,
472
488
  }),
473
489
  scaleSources: Object.freeze({
474
490
  entryValidator: isScaleSourceEntry,
@@ -536,6 +552,7 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
536
552
  customScale: Object.freeze({
537
553
  entryValidator: isScaleEntry,
538
554
  expectsArray: true,
555
+ nonEmpty: true,
539
556
  }),
540
557
  checkMathBounds: Object.freeze({
541
558
  entryValidator: isBoolean,
@@ -579,8 +596,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
579
596
  }),
580
597
  scale: Object.freeze({
581
598
  allowLiterals: ['auto'],
582
- entryValidator: isScaleEntryOrAuto,
599
+ entryValidator: isScaleEntry,
583
600
  expectsArray: true,
601
+ nonEmpty: true,
584
602
  }),
585
603
  scaleSources: Object.freeze({
586
604
  entryValidator: isScaleSourceEntry,
@@ -809,6 +827,7 @@ module.exports = {
809
827
  PREFER_TOKEN_VALIDATION_SCHEMA,
810
828
  USE_SCALE_POSSIBLE_OPTIONS,
811
829
  USE_SCALE_VALIDATION_SCHEMA,
830
+ buildGroupScales,
812
831
  buildScaleOptions,
813
832
  buildTokenOptions,
814
833
  SCALED_GROUPS,