stylelint-plugin-rhythmguard 2.2.0 → 3.1.0

package/src/utils/token-sources.js

@@ -32,7 +32,13 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   motion: /^--(?:motion|duration|delay|ease|easing)-/,
   size: /^--(?:size|width|height|container)-/,
   // Anchored or prefixed (--spacing-4, --lb-spacing-md, bare Tailwind v4 --spacing), never letter-/word-spacing.
-  spacing: /(?:^--|-)(?<!letter-)(?<!word-)(?:space|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)-/,
 });
 
@@ -62,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;
@@ -109,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}`;
@@ -168,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,
   };
 }
 
@@ -231,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 [];
@@ -441,6 +719,7 @@ module.exports = {
   VALID_TOKEN_KINDS,
   VALID_TOKEN_SOURCE_FORMATS,
   addDefinition,
+  collectScssTokens,
   createTokenKindMatcher,
   getNormalizedValueKeys,
   normalizeTokenKind,

package/types/__checks__/consumer.ts

@@ -15,23 +15,17 @@ import eslintPlugin from 'stylelint-plugin-rhythmguard/eslint';
 import { getScalePreset, listScalePresetNames } from 'stylelint-plugin-rhythmguard/presets';
 import recommended from 'stylelint-plugin-rhythmguard/configs/recommended';
 import embed from 'stylelint-plugin-rhythmguard/configs/embed';
-import reactTailwind from 'stylelint-plugin-rhythmguard/configs/react-tailwind';
 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 = {

package/types/audit.d.ts

@@ -60,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;
@@ -72,7 +77,8 @@ export interface AuditFinding {
   key?: string;
   line?: number;
   message: string;
-  property?: string;
+  /** CSS property of the declaration, recovered from the source. Null when the position is not inside a declaration. CSS findings only. */
+  property?: string | null;
   rule?: string;
   type: string;
   value?: string;
@@ -88,7 +94,7 @@ export interface AuditBaselineComparison {
   [key: string]: unknown;
 }
 
-export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-sources";
+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. */
@@ -108,6 +114,10 @@ export interface AuditReport {
     motion: AuditFinding[];
     tailwind: AuditFinding[];
   };
+  /** Off-scale CSS findings counted by property, top ten. */
+  offScaleProperties?: Record<string, number>;
+  /** Off-scale CSS findings counted by value, top ten. */
+  offScaleValues?: Record<string, number>;
   scanned: AuditScanned;
   summary: AuditSummary;
   [key: string]: unknown;
@@ -125,6 +135,7 @@ export interface AuditContractReport {
     scale: {
       cleanliness?: unknown;
       files: string[];
+      offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;

package/types/index.d.ts

@@ -39,11 +39,7 @@ export interface RhythmguardPlugin extends Array<StylelintRuleModule> {
   audit: typeof auditApi;
   configs: {
     embed: RhythmguardStylelintConfig;
-    expanded: RhythmguardStylelintConfig;
-    logical: RhythmguardStylelintConfig;
-    migration: RhythmguardStylelintConfig;
     motion: RhythmguardStylelintConfig;
-    "react-tailwind": RhythmguardStylelintConfig;
     recommended: RhythmguardStylelintConfig;
     strict: RhythmguardStylelintConfig;
     tailwind: RhythmguardStylelintConfig;

package/types/shared.d.ts

@@ -10,6 +10,8 @@ export interface ScaleSource {
   /** `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 {

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/logical.mjs

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

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;