stylelint-plugin-rhythmguard 2.1.0 → 3.0.0

package/src/utils/token-sources.js

@@ -31,7 +31,14 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   radius: /^--radius-/,
   motion: /^--(?:motion|duration|delay|ease|easing)-/,
   size: /^--(?:size|width|height|container)-/,
-  spacing: /^--(?:space|spacing)-/,
+  // Anchored or prefixed (--spacing-4, --lb-spacing-md, bare Tailwind v4 --spacing), never letter-/word-spacing.
+  // CSS custom properties (--spacing-4, --lb-spacing-md, bare --spacing) and Sass
+  // variables or map entries ($spacer, $spacers.3, $system-spacing.small.2).
+  // Custom properties may carry a namespace (--lb-spacing-md, --mantine-spacing-xs, bare
+  // --spacing) but never letter-/word-spacing. Sass names must start with the scale word
+  // (an optional `system-` prefix allowed): $spacer, $spacers.3, $spacing-01, $system-spacing.
+  // Component variables such as $dropdown-spacer or $card-spacer-y are not scale tokens.
+  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing)(?:-|$))/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -61,6 +68,15 @@ function normalizeTokenKind(kind) {
   return normalized;
 }
 
+function createPatternMatcher(pattern, fallback) {
+  try {
+    const regex = new RegExp(pattern);
+    return (token) => regex.test(token);
+  } catch {
+    return fallback;
+  }
+}
+
 function createTokenKindMatcher(kind) {
   const normalizedKind = normalizeTokenKind(kind);
   const pattern = TOKEN_KIND_PATTERNS[normalizedKind] || TOKEN_KIND_PATTERNS.spacing;
@@ -108,16 +124,19 @@ function parseTokenSources({
     }
 
     let tokens = [];
+    const matchesSource = normalizedSource.tokenPattern
+      ? createPatternMatcher(normalizedSource.tokenPattern, matchesKind)
+      : matchesKind;
     try {
       if (normalizedSource.format === 'css') {
-        tokens = collectCssTokens(text, matchesKind);
+        tokens = collectCssTokens(text, matchesSource);
       } else {
         const parsed = JSON.parse(text);
         const detectedFormat = normalizedSource.requestedFormat === 'auto'
           ? detectJsonTokenFormat(parsed)
           : normalizedSource.format;
         sourceReport.format = detectedFormat;
-        tokens = collectJsonTokens(parsed, matchesKind);
+        tokens = collectJsonTokens(parsed, matchesSource);
       }
     } catch (err) {
       const warning = `Unable to parse token source ${normalizedSource.displayPath}: ${err.message}`;
@@ -167,6 +186,9 @@ function normalizeTokenSource(source) {
     format: requestedFormat === 'auto' ? detectSourceFormat(resolvedPath) : requestedFormat,
     requestedFormat,
     resolvedPath,
+    // Optional per-source override for packages that name spacing tokens differently
+    // (Primer's --base-size-*). Falls back to the kind matcher when absent.
+    tokenPattern: typeof source.tokenPattern === 'string' && source.tokenPattern ? source.tokenPattern : null,
   };
 }
 
@@ -230,9 +252,266 @@ function collectCssTokens(source, matchesKind) {
     });
   }
 
+  tokens.push(...collectScssTokens(source, matchesKind));
+  return tokens;
+}
+
+/**
+ * Sass variables and maps as token sources. Handles `$spacer: 1rem`, maps such
+ * as `$spacers: (1: $spacer * .25, ...)` including nested maps, variable
+ * references, `* / + -` arithmetic and `math.div()`. Anything it cannot
+ * evaluate (function calls, strings, keywords, interpolated keys, cycles) is
+ * skipped rather than guessed. Token names are `$name` or `$name.key.path`.
+ */
+function collectScssTokens(source, matchesKind) {
+  const declarations = parseScssDeclarations(source);
+  const cache = new Map();
+
+  const resolveVariable = (name, stack) => {
+    if (cache.has(name)) {
+      return cache.get(name);
+    }
+    if (stack.has(name) || !declarations.has(name)) {
+      return null;
+    }
+    stack.add(name);
+    const raw = declarations.get(name);
+    const value = isScssMap(raw) ? null : evaluateScssExpression(raw, resolveVariable, stack);
+    stack.delete(name);
+    cache.set(name, value);
+    return value;
+  };
+
+  const tokens = [];
+  const push = (tokenName, value) => {
+    if (!value || !matchesKind(tokenName)) {
+      return;
+    }
+    tokens.push({ token: tokenName, value: formatScssValue(value) });
+  };
+
+  for (const [name, raw] of declarations) {
+    const tokenName = `$${name}`;
+    if (isScssMap(raw)) {
+      walkScssMap(raw, [tokenName], (pathName, expression) => {
+        push(pathName, evaluateScssExpression(expression, resolveVariable, new Set()));
+      });
+      continue;
+    }
+    push(tokenName, resolveVariable(name, new Set()));
+  }
+
+  return tokens;
+}
+
+function stripScssComments(source) {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function parseScssDeclarations(source) {
+  const text = stripScssComments(source);
+  const declarations = new Map();
+  const startPattern = /(?:^|\n)[ \t]*\$([\w-]+)[ \t]*:/g;
+  let match;
+
+  while ((match = startPattern.exec(text)) !== null) {
+    const name = match[1];
+    let index = match.index + match[0].length;
+    let depth = 0;
+    let quote = null;
+    let value = '';
+
+    for (; index < text.length; index += 1) {
+      const char = text[index];
+      if (quote) {
+        value += char;
+        if (char === quote) quote = null;
+        continue;
+      }
+      if (char === '"' || char === "'") {
+        quote = char;
+      } else if (char === '(') {
+        depth += 1;
+      } else if (char === ')') {
+        depth -= 1;
+      } else if (char === ';' && depth === 0) {
+        break;
+      }
+      value += char;
+    }
+
+    startPattern.lastIndex = index;
+    const cleaned = value.replace(/!(default|global)\b/g, '').trim();
+    if (cleaned && !declarations.has(name)) {
+      declarations.set(name, cleaned);
+    }
+  }
+
+  return declarations;
+}
+
+function isScssMap(raw) {
+  return raw.startsWith('(') && raw.endsWith(')') && /:/.test(raw);
+}
+
+function splitTopLevel(text, separator) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let current = '';
+  for (const char of text) {
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '(') depth += 1;
+    else if (char === ')') depth -= 1;
+    if (char === separator && depth === 0) {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+function walkScssMap(raw, pathSegments, visit) {
+  const inner = raw.slice(1, -1);
+  for (const entry of splitTopLevel(inner, ',')) {
+    const pair = splitTopLevel(entry, ':');
+    if (pair.length < 2) continue;
+    const key = pair[0].trim().replace(/^["']|["']$/g, '');
+    const expression = pair.slice(1).join(':').trim();
+    if (!key || key.includes('#{')) continue;
+    const nextPath = [...pathSegments, key];
+    if (isScssMap(expression)) {
+      walkScssMap(expression, nextPath, visit);
+    } else {
+      visit(nextPath.join('.'), expression);
+    }
+  }
+}
+
+const SCSS_TOKEN_PATTERN = /\s*(?:(-?(?:\d+\.?\d*|\.\d+)[a-zA-Z%]*)|(\$[\w-]+)|([a-zA-Z_][\w.-]*)\s*\(|([()*/+,-]))/y;
+
+function tokenizeScssExpression(expression) {
+  const tokens = [];
+  let index = 0;
+  while (index < expression.length) {
+    SCSS_TOKEN_PATTERN.lastIndex = index;
+    const match = SCSS_TOKEN_PATTERN.exec(expression);
+    if (!match) {
+      if (/\s/.test(expression[index])) {
+        index += 1;
+        continue;
+      }
+      return null;
+    }
+    index = SCSS_TOKEN_PATTERN.lastIndex;
+    if (match[1] !== undefined) tokens.push({ type: 'number', raw: match[1] });
+    else if (match[2] !== undefined) tokens.push({ type: 'var', name: match[2].slice(1) });
+    else if (match[3] !== undefined) tokens.push({ type: 'call', name: match[3] });
+    else tokens.push({ type: 'op', value: match[4] });
+  }
   return tokens;
 }
 
+function evaluateScssExpression(expression, resolveVariable, stack) {
+  const tokens = tokenizeScssExpression(expression.trim());
+  if (!tokens || tokens.length === 0) {
+    return null;
+  }
+  let position = 0;
+  const peek = () => tokens[position];
+  const next = () => tokens[position++];
+
+  const parseNumber = (raw) => {
+    const parsed = parseLengthToken(raw);
+    if (parsed) return { number: parsed.number, unit: parsed.unit };
+    const numeric = Number(raw);
+    return Number.isFinite(numeric) ? { number: numeric, unit: '' } : null;
+  };
+
+  const combine = (left, op, right) => {
+    if (!left || !right) return null;
+    if (op === '*') {
+      if (left.unit && right.unit) return null;
+      return { number: left.number * right.number, unit: left.unit || right.unit };
+    }
+    if (op === '/') {
+      if (right.number === 0) return null;
+      if (right.unit && right.unit !== left.unit) return null;
+      return { number: left.number / right.number, unit: right.unit ? '' : left.unit };
+    }
+    const compatible = left.unit === right.unit || left.number === 0 || right.number === 0;
+    if (!compatible) return null;
+    return { number: op === '+' ? left.number + right.number : left.number - right.number, unit: left.unit || right.unit };
+  };
+
+  const parsePrimary = () => {
+    const token = next();
+    if (!token) return null;
+    if (token.type === 'number') return parseNumber(token.raw);
+    if (token.type === 'var') return resolveVariable(token.name, stack);
+    if (token.type === 'op' && token.value === '-') {
+      const value = parsePrimary();
+      return value ? { number: -value.number, unit: value.unit } : null;
+    }
+    if (token.type === 'op' && token.value === '(') {
+      const value = parseExpression();
+      const closing = next();
+      return closing && closing.type === 'op' && closing.value === ')' ? value : null;
+    }
+    if (token.type === 'call') {
+      const args = [];
+      let current = parseExpression();
+      args.push(current);
+      while (peek() && peek().type === 'op' && peek().value === ',') {
+        next();
+        args.push(parseExpression());
+      }
+      const closing = next();
+      if (!closing || closing.type !== 'op' || closing.value !== ')') return null;
+      if (token.name === 'math.div' && args.length === 2) return combine(args[0], '/', args[1]);
+      return null;
+    }
+    return null;
+  };
+
+  const parseTerm = () => {
+    let value = parsePrimary();
+    while (peek() && peek().type === 'op' && (peek().value === '*' || peek().value === '/')) {
+      const op = next().value;
+      value = combine(value, op, parsePrimary());
+    }
+    return value;
+  };
+
+  const parseExpression = () => {
+    let value = parseTerm();
+    while (peek() && peek().type === 'op' && (peek().value === '+' || peek().value === '-')) {
+      const op = next().value;
+      value = combine(value, op, parseTerm());
+    }
+    return value;
+  };
+
+  const result = parseExpression();
+  return position === tokens.length ? result : null;
+}
+
+function formatScssValue(value) {
+  const rounded = Math.round(value.number * 1000) / 1000;
+  if (rounded === 0) return '0';
+  return `${rounded}${value.unit}`;
+}
+
 function collectJsonTokens(parsed, matchesKind) {
   if (!isPlainObject(parsed)) {
     return [];
@@ -377,6 +656,34 @@ function addDefinition(definitions, {
   definitions.set(token, entry);
 }
 
+const CALC_LENGTH_TIMES_VAR = /^calc\(\s*(-?[\d.]+(?:px|rem|em)?)\s*\*\s*var\([^()]*\)\s*\)$/i;
+const CALC_VAR_TIMES_LENGTH = /^calc\(\s*var\([^()]*\)\s*\*\s*(-?[\d.]+(?:px|rem|em)?)\s*\)$/i;
+
+/**
+ * Parse the length a token value carries. Accepts plain lengths and the
+ * `calc(<length> * var(--factor))` form design systems use for scaling
+ * (Radix Themes: `--space-1: calc(4px * var(--scaling))`).
+ */
+function parseTokenValueLength(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const direct = parseLengthToken(trimmed);
+  if (direct) {
+    return direct;
+  }
+
+  const match = trimmed.match(CALC_LENGTH_TIMES_VAR) || trimmed.match(CALC_VAR_TIMES_LENGTH);
+  if (!match) {
+    return null;
+  }
+
+  const inner = parseLengthToken(match[1]);
+  return inner ? { ...inner, raw: trimmed } : null;
+}
+
 function getNormalizedValueKeys(value, baseFontSize = 16) {
   if (value === null || value === undefined) {
     return [];
@@ -388,7 +695,7 @@ function getNormalizedValueKeys(value, baseFontSize = 16) {
   }
 
   const keys = new Set([raw]);
-  const parsed = parseLengthToken(raw);
+  const parsed = parseTokenValueLength(raw);
   if (!parsed) {
     return Array.from(keys);
   }
@@ -412,9 +719,11 @@ module.exports = {
   VALID_TOKEN_KINDS,
   VALID_TOKEN_SOURCE_FORMATS,
   addDefinition,
+  collectScssTokens,
   createTokenKindMatcher,
   getNormalizedValueKeys,
   normalizeTokenKind,
   normalizeTokenSourceFormat,
   parseTokenSources,
+  parseTokenValueLength,
 };

package/types/__checks__/consumer.ts

@@ -14,21 +14,18 @@ import { createAuditReport, toAuditContractReport } from 'stylelint-plugin-rhyth
 import eslintPlugin from 'stylelint-plugin-rhythmguard/eslint';
 import { getScalePreset, listScalePresetNames } from 'stylelint-plugin-rhythmguard/presets';
 import recommended from 'stylelint-plugin-rhythmguard/configs/recommended';
-import reactTailwind from 'stylelint-plugin-rhythmguard/configs/react-tailwind';
+import embed from 'stylelint-plugin-rhythmguard/configs/embed';
 import useScale, { ruleName as useScaleName } from 'stylelint-plugin-rhythmguard/rules/use-scale';
 
 const pluginConfigs: readonly RhythmguardStylelintConfig[] = [
   plugin.configs.recommended,
   plugin.configs.strict,
   plugin.configs.tailwind,
-  plugin.configs.expanded,
-  plugin.configs.logical,
-  plugin.configs.migration,
   plugin.configs.motion,
-  plugin.configs['react-tailwind'],
   configs.recommended,
+  plugin.configs.embed,
+  embed,
   recommended,
-  reactTailwind,
 ];
 
 const ruleOptions: RhythmguardRuleOptions = {
@@ -38,6 +35,12 @@ const ruleOptions: RhythmguardRuleOptions = {
   tokenMapFromCssCustomProperties: true,
 };
 
+const autoScaleOptions: RhythmguardRuleOptions = {
+  scale: 'auto',
+  scaleSources: ['./tokens.json', { path: './theme.css', format: 'css' }],
+  tailwindConfigPath: './tailwind.config.mjs',
+};
+
 const useScaleRule = rules['rhythmguard/use-scale'];
 const fixable: boolean | undefined = useScaleRule.meta.fixable;
 const docUrl: string | undefined = useScale.meta.url;
@@ -59,6 +62,7 @@ async function runAudit(): Promise<AuditContractReport> {
 
 void pluginConfigs;
 void ruleOptions;
+void autoScaleOptions;
 void fixable;
 void docUrl;
 void name;

package/types/audit.d.ts

@@ -37,7 +37,8 @@ export interface AuditOptions {
   noConfig?: boolean;
   /** Write rendered output to this file instead of stdout (equivalent to `--output`). */
   outputPath?: string;
-  scale?: Array<number | string>;
+  /** Explicit scale values, or `"auto"` to infer from token sources, then scanned CSS, then the default. */
+  scale?: Array<number | string> | "auto";
   since?: string;
   sinceBaseline?: boolean;
   staged?: boolean;
@@ -59,7 +60,12 @@ export interface AuditSummary {
 }
 
 export interface AuditScanned {
+  /** Authored stylesheets scanned: .css plus .scss when postcss-scss is available. */
   cssFiles: number;
+  /** .scss files found. Audited through postcss-scss when it resolves. */
+  scssFiles?: number;
+  /** .scss files found but not audited because postcss-scss is not installed. */
+  scssSkipped?: number;
   templateFiles: number;
   totalFiles?: number;
   [key: string]: unknown;
@@ -87,8 +93,19 @@ export interface AuditBaselineComparison {
   [key: string]: unknown;
 }
 
+export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
+
+export interface AuditScale {
+  /** Files the scale was derived from (token sources or scanned stylesheets). Empty for explicit, default and fallback. */
+  files: string[];
+  source: AuditScaleSource;
+  tokenCount: number;
+  values: Array<number | string>;
+}
+
 export interface AuditReport {
   baseline?: AuditBaselineComparison | null;
+  scale?: AuditScale | null;
   config?: string | null;
   directory: string;
   findings: {
@@ -112,8 +129,11 @@ export interface AuditContractReport {
     motion?: unknown;
     scale: {
       cleanliness?: unknown;
+      files: string[];
       offScaleValues?: unknown;
+      source: AuditScaleSource;
       tokenOpportunities?: unknown;
+      values: Array<number | string> | null;
     };
     tokens?: unknown;
   };

package/types/index.d.ts

@@ -14,6 +14,7 @@ export type {
   RhythmguardRuleOptions,
   RhythmguardStylelintConfig,
   ScalePresetMetadata,
+  ScaleSource,
   ScaleValue,
 } from "./shared";
 export type {
@@ -22,6 +23,8 @@ export type {
   AuditFinding,
   AuditOptions,
   AuditReport,
+  AuditScale,
+  AuditScaleSource,
   AuditScanned,
   AuditSummary,
   AuditTokenKind,
@@ -35,11 +38,8 @@ export type { StylelintRuleModule } from "./rule";
 export interface RhythmguardPlugin extends Array<StylelintRuleModule> {
   audit: typeof auditApi;
   configs: {
-    expanded: RhythmguardStylelintConfig;
-    logical: RhythmguardStylelintConfig;
-    migration: RhythmguardStylelintConfig;
+    embed: RhythmguardStylelintConfig;
     motion: RhythmguardStylelintConfig;
-    "react-tailwind": RhythmguardStylelintConfig;
     recommended: RhythmguardStylelintConfig;
     strict: RhythmguardStylelintConfig;
     tailwind: RhythmguardStylelintConfig;

package/types/shared.d.ts

@@ -2,13 +2,36 @@ export type ScaleValue = number | string;
 
 export type RuleSeverity = boolean | "always" | "never";
 
+export interface ScaleSource {
+  /** Directory that a relative `path` resolves from. Defaults to the working directory. */
+  baseDir?: string;
+  /** Alias for `path`. */
+  file?: string;
+  /** `auto` (default), `css`, `flat-json`, `style-dictionary`, or `dtcg`. */
+  format?: string;
+  path?: string;
+  /** Regex for token names in this file, overriding the spacing kind matcher (for packages that name spacing differently). */
+  tokenPattern?: string;
+}
+
 export interface RhythmguardRuleOptions {
+  /** Exempt non-zero lengths of one CSS pixel or less (1px, -1px, 0.5px, 0.0625rem). Default true. */
+  allowHairlines?: boolean;
   baseFontSize?: number;
   customScale?: ScaleValue[];
   includeMathFunctions?: boolean;
   preset?: string;
   properties?: Array<string | RegExp>;
-  scale?: ScaleValue[];
+  /**
+   * Allowed values, or `"auto"` to infer the scale from spacing tokens: `scaleSources`,
+   * then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom
+   * properties, then `tailwindConfigPath`, falling back to the `rhythmic-4` preset.
+   */
+  scale?: ScaleValue[] | "auto";
+  /** Token files consulted first when `scale` is `"auto"`. */
+  scaleSources?: Array<string | ScaleSource>;
+  /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */
+  tailwindConfigPath?: string;
   tokenMap?: Record<string, string>;
   tokenMapFile?: string;
   tokenMapFromCssCustomProperties?: boolean;

package/src/configs/expanded.js

@@ -1,27 +0,0 @@
-'use strict';
-
-module.exports = {
-  plugins: ['stylelint-plugin-rhythmguard'],
-  rules: {
-    'rhythmguard/use-scale': [
-      true,
-      {
-        propertyGroups: ['spacing', 'radius', 'typography', 'size'],
-        scale: [0, 2, 4, 8, 12, 16, 24, 32, 40, 48, 64],
-      },
-    ],
-    'rhythmguard/no-offscale-transform': [
-      true,
-      {
-        scale: [0, 4, 8, 12, 16, 24, 32],
-      },
-    ],
-    'rhythmguard/prefer-token': [
-      true,
-      {
-        propertyGroups: ['spacing', 'radius'],
-        tokenPattern: '^--space-|^--radius-',
-      },
-    ],
-  },
-};

package/src/configs/expanded.mjs

@@ -1,4 +0,0 @@
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const config = require('./expanded.js');
-export default config;

package/src/configs/logical.js

@@ -1,16 +0,0 @@
-'use strict';
-
-module.exports = {
-  extends: [
-    'stylelint-plugin-logical-css/configs/recommended',
-    'stylelint-plugin-rhythmguard/configs/strict',
-  ],
-  rules: {
-    'rhythmguard/use-scale': [
-      true,
-      {
-        propertyGroups: ['spacing', 'size'],
-      },
-    ],
-  },
-};

package/src/configs/migration.js

@@ -1,31 +0,0 @@
-'use strict';
-
-module.exports = {
-  plugins: ['stylelint-plugin-rhythmguard'],
-  rules: {
-    'rhythmguard/use-scale': [
-      true,
-      {
-        propertyGroups: ['spacing', 'radius'],
-        scale: [0, 2, 4, 8, 12, 16, 24, 32, 40, 48, 64],
-      },
-    ],
-    'rhythmguard/prefer-token': [
-      true,
-      {
-        allowNumericScale: true,
-        propertyGroups: ['spacing', 'radius'],
-        tokenMapFromCssCustomProperties: true,
-        tokenMapFromTailwindSpacing: true,
-        tailwindConfigPath: './tailwind.config.js',
-        tokenPattern: '^--space-|^--radius-',
-      },
-    ],
-    'rhythmguard/no-offscale-transform': [
-      true,
-      {
-        scale: [0, 4, 8, 12, 16, 24, 32],
-      },
-    ],
-  },
-};

package/src/configs/migration.mjs

@@ -1,4 +0,0 @@
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const config = require('./migration.js');
-export default config;

package/src/configs/react-tailwind.js

@@ -1,25 +0,0 @@
-'use strict';
-
-module.exports = {
-  extends: [
-    'stylelint-plugin-rhythmguard/configs/tailwind',
-  ],
-  ignoreFiles: [
-    '.next/**',
-    'out/**',
-    'node_modules/**',
-  ],
-  overrides: [
-    {
-      files: ['**/*.module.css'],
-      rules: {
-        'rhythmguard/use-scale': [
-          true,
-          {
-            propertyGroups: ['spacing', 'radius'],
-          },
-        ],
-      },
-    },
-  ],
-};

package/src/configs/react-tailwind.mjs

@@ -1,4 +0,0 @@
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const config = require('./react-tailwind.js');
-export default config;