stylelint-plugin-rhythmguard 3.13.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.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,23 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.14.0] - 2026-10-19
10
+
11
+ ### Added
12
+
13
+ - A configured token source that yields no spacing tokens is a warning, whatever its format. A DTCG file holding only colors, a stylesheet with no custom properties, or a design-tool export whose group is called `dimension` gave `0` tokens and a silent fallback scale. Each `--token-source` and `audit.tokenSources` file that parses but yields nothing now carries `Token source <file> (<format>) yielded no spacing tokens; ...` in the audit's token source report (`contracts.tokens.sources[].warnings` in JSON, the Markdown Token Sources table, and a `!` line under the source in the text output, which now prints every token source warning there), and `rhythmguard doctor` prints the same as a `!` warning line that does not fail the run, along with any parse or skip warning the audit would give for that file. With `--token-kind` the warning names that kind. Stylesheets found by the scan and installed token packages are not configured sources and get no such warning. `parseTokenSources` takes `warnWhenEmpty: true` for the same check; it is off by default. ([#163](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/163))
14
+ - The DTCG group's 2025.10 conformance fixtures for dimensions and dimension references run in the unit tests, vendored under `test/fixtures/dtcg-test-suite/` from design-tokens/community-group at `8e43819` (W3C 3-clause BSD License). They are not part of the npm package. ([#163](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/163))
15
+
16
+ ### Fixed
17
+
18
+ - DTCG token sources read the rest of the 2025.10 dimension forms the conformance suite covers. A `$ref` token (`"$ref": "#/base/$value/fontSize"`) was dropped without a word; it is now read through its JSON Pointer within the file, so a pointer to a `{ value, unit }` dimension gives that length. A `$ref` that names nothing, or a `dimension` token pointing at a bare number, is skipped with a warning; one pointing at a color or a composite is not a length and is left out as a color `$value` is. A dimension object without a number `value` and a `unit` (`{ "value": "16", "unit": "px" }`, `{ "unit": "px" }`) was dropped silently and is now skipped with a warning naming the token. Only files with such tokens read differently: a `$ref` spacing token can now move an inferred scale. ([#163](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/163))
19
+
20
+ ### Messages
21
+
22
+ - New token source warning (audit and `rhythmguard doctor`): `Token source <file> (<format>) yielded no spacing tokens; spacing tokens are read by name (space, spacing or spacer), so set a tokenPattern on this source if its tokens are named otherwise.`; with another `--token-kind`, `Token source <file> (<format>) yielded no <kind> tokens.`; with `--token-kind all`, `... yielded no tokens.`; for a source with its own `tokenPattern`, `... yielded no tokens matching tokenPattern "<pattern>".`
23
+ - New skip reasons in `Token source <file>: skipped <token> (<reason>).`: `dimension needs a number "value" and a "unit"`, `reference "<pointer>" does not resolve`, `reference "<pointer>" is a number, not a dimension`, `reference cycle through "<pointer>"`.
24
+ - `rhythmguard doctor` prints warnings as `! <warning>` lines, and its summary reads `All checks passed (N warnings).` or `N issues found (N warnings).` when there are any; without warnings it is unchanged.
25
+
9
26
  ## [3.13.0] - 2026-10-18
10
27
 
11
28
  ### Fixed
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
8
8
 
9
9
  [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
10
- [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3130)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
10
+ [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3140)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
11
11
  [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
12
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
13
13
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stylelint-plugin-rhythmguard",
3
- "version": "3.13.0",
3
+ "version": "3.14.0",
4
4
  "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
5
5
  "bin": {
6
6
  "rhythmguard": "src/cli/index.js"
@@ -129,6 +129,9 @@ function appendTokenContractText(lines, tokenContract) {
129
129
  for (const source of sources.slice(0, 5)) {
130
130
  const warningSuffix = source.warnings.length > 0 ? ' (warning)' : '';
131
131
  lines.push(` ${truncate(source.file, 42)} ${source.tokenCount}${warningSuffix}`);
132
+ for (const warning of source.warnings) {
133
+ lines.push(` ! ${warning}`);
134
+ }
132
135
  }
133
136
  }
134
137
 
@@ -43,10 +43,12 @@ async function createAuditReport(options) {
43
43
  // A --staged run reads each changed file as the index holds it.
44
44
  const readSource = scanFiles.readSource || readSourceFromDisk;
45
45
 
46
+ // A configured source that gives nothing is a warning, not a silent fallback (issue #163).
46
47
  const tokenSourceResult = parseTokenSources({
47
48
  baseFontSize: parsed.baseFontSize,
48
49
  sources: parsed.tokenSources,
49
50
  tokenKind: parsed.tokenKind,
51
+ warnWhenEmpty: true,
50
52
  });
51
53
 
52
54
  // The spacing scale always reads spacing tokens; --token-kind shapes the token contract only (issue #260).
package/src/cli/doctor.js CHANGED
@@ -6,7 +6,8 @@ const { applyAuditConfig, loadAuditConfig, resolveIgnorePatterns } = require('..
6
6
  const { createDefaultAuditOptions } = require('../audit/shared');
7
7
  const { normalizeDecisions } = require('../core/decisions');
8
8
  const { readJsonFile } = require('../core/json');
9
- const { normalizeTokenSourceFormat } = require('../core/token-sources');
9
+ const { normalizeTokenSourceEntry } = require('../core/token-source-entries');
10
+ const { normalizeTokenSourceFormat, parseTokenSources } = require('../core/token-sources');
10
11
 
11
12
  const HELP = `Usage: rhythmguard doctor
12
13
 
@@ -37,6 +38,14 @@ function skip(msg) {
37
38
  process.stdout.write(`- ${msg}\n`);
38
39
  }
39
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
+
40
49
  // Check 1: Stylelint installed
41
50
  function checkStylelint() {
42
51
  try {
@@ -313,12 +322,29 @@ function checkRhythmguardTokenSources(audit, baseDir) {
313
322
 
314
323
  if (fs.existsSync(path.resolve(baseDir, sourcePath))) {
315
324
  pass(`token source found (${sourcePath})`);
325
+ warnAboutTokenSource(source, baseDir);
316
326
  } else {
317
327
  fail(`token source not found (${sourcePath})`, 'Update audit.tokenSources or create the token file');
318
328
  }
319
329
  }
320
330
  }
321
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
+
322
348
  function checkRhythmguardMotionConfig(audit) {
323
349
  if (audit.includeMotion === undefined) {
324
350
  skip('motion audit check skipped (not configured)');
@@ -374,11 +400,12 @@ function run() {
374
400
 
375
401
  process.stdout.write('\n');
376
402
 
403
+ const warningNote = warnings > 0 ? ` (${warnings} warning${warnings === 1 ? '' : 's'})` : '';
377
404
  if (issues === 0) {
378
- process.stdout.write('All checks passed.\n\n');
405
+ process.stdout.write(`All checks passed${warningNote}.\n\n`);
379
406
  } else {
380
407
  process.stdout.write(
381
- `${issues} issue${issues === 1 ? '' : 's'} found.\n\n`,
408
+ `${issues} issue${issues === 1 ? '' : 's'} found${warningNote}.\n\n`,
382
409
  );
383
410
  }
384
411
 
@@ -87,15 +87,41 @@ function createTokenKindMatcher(kind) {
87
87
  return (token) => pattern.test(token);
88
88
  }
89
89
 
90
+ /**
91
+ * Why a source that parsed gave nothing: what was looked for, and for spacing
92
+ * the naming rule a design-tool export most often misses (issue #163).
93
+ */
94
+ function emptySourceWarning(source, format, tokenKind) {
95
+ const prefix = `Token source ${source.displayPath} (${format}) yielded no`;
96
+ if (source.tokenPattern) {
97
+ return `${prefix} tokens matching tokenPattern "${source.tokenPattern}".`;
98
+ }
99
+ if (tokenKind === 'all') {
100
+ return `${prefix} tokens.`;
101
+ }
102
+ if (tokenKind === 'spacing') {
103
+ return `${prefix} spacing tokens; spacing tokens are read by name (space, spacing or spacer), so set a tokenPattern on this source if its tokens are named otherwise.`;
104
+ }
105
+ return `${prefix} ${tokenKind} tokens.`;
106
+ }
107
+
108
+ /**
109
+ * Read token sources into definitions, with one report per source. With
110
+ * `warnWhenEmpty`, a source that parses but yields no token of the kind read
111
+ * gets a warning too; the audit and `rhythmguard doctor` ask for that for the
112
+ * token sources a project configures.
113
+ */
90
114
  function parseTokenSources({
91
115
  baseFontSize = 16,
92
116
  sources = [],
93
117
  tokenKind = 'spacing',
118
+ warnWhenEmpty = false,
94
119
  } = {}) {
95
120
  const definitions = new Map();
96
121
  const sourceReports = [];
97
122
  const warnings = [];
98
123
  const matchesKind = createTokenKindMatcher(tokenKind);
124
+ const kind = normalizeTokenKind(tokenKind);
99
125
 
100
126
  for (const source of sources) {
101
127
  const normalizedSource = normalizeTokenSource(source);
@@ -156,6 +182,12 @@ function parseTokenSources({
156
182
  warnings.push(warning);
157
183
  }
158
184
 
185
+ if (warnWhenEmpty && tokens.length === 0) {
186
+ const warning = emptySourceWarning(normalizedSource, sourceReport.format, kind);
187
+ sourceReport.warnings.push(warning);
188
+ warnings.push(warning);
189
+ }
190
+
159
191
  for (const token of tokens) {
160
192
  addDefinition(definitions, {
161
193
  baseFontSize,
@@ -972,7 +1004,7 @@ function collectJsonTokens(parsed, matchesKind, onSkip = () => {}) {
972
1004
  return tokens;
973
1005
  }
974
1006
 
975
- function walkJsonTokenGroup(group, segments, tokens, context) {
1007
+ function walkJsonTokenGroup(group, segments, tokens, context, inheritedType = null) {
976
1008
  const { matchesKind, onSkip } = context;
977
1009
  for (const [key, value] of Object.entries(group)) {
978
1010
  if (isMetadataKey(key)) {
@@ -991,7 +1023,9 @@ function walkJsonTokenGroup(group, segments, tokens, context) {
991
1023
  continue;
992
1024
  }
993
1025
 
994
- const leaf = leafTokenValue(value, context.root);
1026
+ // DTCG `$type` applies to the node and, on a group, to every token below it.
1027
+ const type = typeof value.$type === 'string' ? value.$type : inheritedType;
1028
+ const leaf = leafTokenValue(value, context.root, type);
995
1029
  if (leaf !== null) {
996
1030
  const token = key.startsWith('--')
997
1031
  ? key
@@ -1006,7 +1040,7 @@ function walkJsonTokenGroup(group, segments, tokens, context) {
1006
1040
  continue;
1007
1041
  }
1008
1042
 
1009
- walkJsonTokenGroup(value, [...segments, key], tokens, context);
1043
+ walkJsonTokenGroup(value, [...segments, key], tokens, context, type);
1010
1044
  }
1011
1045
  }
1012
1046
 
@@ -1046,6 +1080,9 @@ function tokenFromPrimitive(key, value, segments) {
1046
1080
  const DTCG_DIMENSION_UNITS = new Set(['px', 'rem']);
1047
1081
  const JSON_REFERENCE = /^\{([^{}]+)\}$/;
1048
1082
  const MAX_JSON_REFERENCE_DEPTH = 32;
1083
+ // Raw values that are not plain JSON: a `$ref` token and a malformed dimension.
1084
+ const JSON_POINTER_REF = Symbol('json pointer reference');
1085
+ const INVALID_DIMENSION = Symbol('invalid dimension');
1049
1086
 
1050
1087
  function isDimensionObject(value) {
1051
1088
  return isPlainObject(value)
@@ -1053,9 +1090,30 @@ function isDimensionObject(value) {
1053
1090
  && typeof value.unit === 'string';
1054
1091
  }
1055
1092
 
1093
+ /** `{ "value": "16", "unit": "px" }` or `{ "unit": "px" }`: shaped like a dimension, not one. */
1094
+ function isMalformedDimension(value) {
1095
+ return isPlainObject(value)
1096
+ && !isDimensionObject(value)
1097
+ && (Object.prototype.hasOwnProperty.call(value, 'value') || Object.prototype.hasOwnProperty.call(value, 'unit'));
1098
+ }
1099
+
1100
+ /**
1101
+ * A DTCG 2025.10 `$ref` token: a JSON Pointer into the same file
1102
+ * (`"$ref": "#/base/$value/fontSize"`) in place of `$value`. Only a node with
1103
+ * nothing but `$` keys is one, so a group that happens to carry `$ref` is
1104
+ * still walked as a group.
1105
+ */
1106
+ function jsonPointerOf(node) {
1107
+ if (typeof node.$ref !== 'string' || Object.prototype.hasOwnProperty.call(node, '$value')) {
1108
+ return null;
1109
+ }
1110
+ return Object.keys(node).every((key) => key.startsWith('$')) ? node.$ref : null;
1111
+ }
1112
+
1056
1113
  /**
1057
- * The raw value a token node holds: `$value` (DTCG, any shape) or a string or
1058
- * number `value` (Style Dictionary). Undefined when the node is a group.
1114
+ * The raw value a token node holds: `$value` (DTCG, any shape), a `$ref`
1115
+ * pointer, or a string or number `value` (Style Dictionary). Undefined when
1116
+ * the node is a group or holds something other than a length (a color).
1059
1117
  */
1060
1118
  function rawTokenValue(node) {
1061
1119
  if (!isPlainObject(node)) {
@@ -1066,7 +1124,11 @@ function rawTokenValue(node) {
1066
1124
  if (typeof raw === 'string' || typeof raw === 'number' || isDimensionObject(raw)) {
1067
1125
  return raw;
1068
1126
  }
1069
- return undefined;
1127
+ return isMalformedDimension(raw) ? { [INVALID_DIMENSION]: true } : undefined;
1128
+ }
1129
+ const pointer = jsonPointerOf(node);
1130
+ if (pointer !== null) {
1131
+ return { [JSON_POINTER_REF]: pointer };
1070
1132
  }
1071
1133
  if (isDimensionObject(node)) {
1072
1134
  // `{ "value": 4, "unit": "rem" }` is one dimension, not a number with metadata.
@@ -1093,16 +1155,82 @@ function lookupJsonReference(root, reference) {
1093
1155
  return isPlainObject(node) ? rawTokenValue(node) : node;
1094
1156
  }
1095
1157
 
1158
+ /** The value a same-file JSON Pointer (`#/a/b/0`, RFC 6901) names, or undefined. */
1159
+ function lookupJsonPointer(root, pointer) {
1160
+ if (pointer === '#') {
1161
+ return root;
1162
+ }
1163
+ if (!pointer.startsWith('#/')) {
1164
+ return undefined;
1165
+ }
1166
+ let node = root;
1167
+ for (const encoded of pointer.slice(2).split('/')) {
1168
+ let segment;
1169
+ try {
1170
+ segment = decodeURIComponent(encoded).replace(/~1/g, '/').replace(/~0/g, '~');
1171
+ } catch {
1172
+ return undefined;
1173
+ }
1174
+ if (Array.isArray(node)) {
1175
+ if (!/^(?:0|[1-9]\d*)$/.test(segment) || Number(segment) >= node.length) {
1176
+ return undefined;
1177
+ }
1178
+ node = node[Number(segment)];
1179
+ } else if (isPlainObject(node) && Object.prototype.hasOwnProperty.call(node, segment)) {
1180
+ node = node[segment];
1181
+ } else {
1182
+ return undefined;
1183
+ }
1184
+ }
1185
+ return node;
1186
+ }
1187
+
1188
+ /**
1189
+ * A `$ref` token's value. The pointer names a value inside the file, usually a
1190
+ * `$value` or a part of one. A dimension object or a string is read as any
1191
+ * `$value` is; a number is read too, except for a `dimension` token, which
1192
+ * needs the whole `{ value, unit }` object. A pointer to a color or a
1193
+ * composite is not a length and is left out quietly; one that names nothing is
1194
+ * skipped with a warning.
1195
+ */
1196
+ function resolveJsonPointer(pointer, root, stack, type) {
1197
+ if (stack.has(pointer)) {
1198
+ return { skipped: `reference cycle through "${pointer}"`, value: null };
1199
+ }
1200
+ const target = lookupJsonPointer(root, pointer);
1201
+ if (target === undefined) {
1202
+ return { skipped: `reference "${pointer}" does not resolve`, value: null };
1203
+ }
1204
+ if (typeof target === 'number' && type === 'dimension') {
1205
+ return { skipped: `reference "${pointer}" is a number, not a dimension`, value: null };
1206
+ }
1207
+ if (typeof target === 'string' || typeof target === 'number' || isDimensionObject(target) || isMalformedDimension(target)) {
1208
+ stack.add(pointer);
1209
+ const resolved = resolveJsonValue(isMalformedDimension(target) ? { [INVALID_DIMENSION]: true } : target, root, stack, type);
1210
+ stack.delete(pointer);
1211
+ return resolved;
1212
+ }
1213
+ return { value: null };
1214
+ }
1215
+
1096
1216
  /**
1097
1217
  * A raw token value as a string: a number as written, a dimension object as
1098
- * `4px` or `0.75rem`, a whole-value reference followed through the file. A
1099
- * reference that cannot be followed (a missing target, a cycle) keeps its text,
1100
- * as before, and reads as a non-length; a dimension in another unit is skipped.
1218
+ * `4px` or `0.75rem`, a reference (`{spacing.2}` or a `$ref` pointer)
1219
+ * followed through the file. A `{}` reference that cannot be followed (a
1220
+ * missing target, a cycle) keeps its text, as before, and reads as a
1221
+ * non-length; a `$ref` that cannot be followed, a dimension in another unit
1222
+ * and a malformed dimension are skipped.
1101
1223
  */
1102
- function resolveJsonValue(raw, root, stack = new Set()) {
1224
+ function resolveJsonValue(raw, root, stack = new Set(), type = null) {
1103
1225
  if (typeof raw === 'number') {
1104
1226
  return { value: String(raw) };
1105
1227
  }
1228
+ if (isPlainObject(raw) && raw[INVALID_DIMENSION]) {
1229
+ return { skipped: 'dimension needs a number "value" and a "unit"', value: null };
1230
+ }
1231
+ if (isPlainObject(raw) && typeof raw[JSON_POINTER_REF] === 'string') {
1232
+ return resolveJsonPointer(raw[JSON_POINTER_REF], root, stack, type);
1233
+ }
1106
1234
  if (isDimensionObject(raw)) {
1107
1235
  const unit = raw.unit.trim().toLowerCase();
1108
1236
  if (!Number.isFinite(raw.value) || !DTCG_DIMENSION_UNITS.has(unit)) {
@@ -1126,7 +1254,7 @@ function resolveJsonValue(raw, root, stack = new Set()) {
1126
1254
  return { value: raw };
1127
1255
  }
1128
1256
  stack.add(target);
1129
- const resolved = resolveJsonValue(next, root, stack);
1257
+ const resolved = resolveJsonValue(next, root, stack, type);
1130
1258
  stack.delete(target);
1131
1259
  if (resolved.value === null && !resolved.skipped) {
1132
1260
  return { value: raw };
@@ -1135,12 +1263,12 @@ function resolveJsonValue(raw, root, stack = new Set()) {
1135
1263
  }
1136
1264
 
1137
1265
  /** The value of a token node, resolved; null when the node is a group, not a token. */
1138
- function leafTokenValue(node, root = node) {
1266
+ function leafTokenValue(node, root = node, type = null) {
1139
1267
  const raw = rawTokenValue(node);
1140
1268
  if (raw === undefined) {
1141
1269
  return null;
1142
1270
  }
1143
- return resolveJsonValue(raw, root);
1271
+ return resolveJsonValue(raw, root, new Set(), type);
1144
1272
  }
1145
1273
 
1146
1274
  function isMetadataKey(key) {
package/types/audit.d.ts CHANGED
@@ -316,6 +316,8 @@ export function parseTokenSources(options?: {
316
316
  baseFontSize?: number;
317
317
  sources?: AuditTokenSource[];
318
318
  tokenKind?: AuditTokenKind;
319
+ /** Warn about a source that parses but yields no token of `tokenKind`, as the audit does. Default false. */
320
+ warnWhenEmpty?: boolean;
319
321
  }): ParsedTokenSources;
320
322
 
321
323
  export function toAuditContractReport(report: AuditReport): AuditContractReport;