stylelint-plugin-rhythmguard 3.2.0 → 3.4.0

package/src/{utils → core}/token-sources.js

@@ -38,7 +38,7 @@ const TOKEN_KIND_PATTERNS = Object.freeze({
   // --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)(?:-|$))/,
+  spacing: /^(?:\$(?:system-)?(?:space|spacing|spacer)s?(?:-|$|\.)|--(?:[\w-]*-)?(?<!letter-)(?<!word-)(?:space|spacing|spacer)(?:-|$))/,
   typography: /^--(?:font|font-size|line-height|leading|tracking|typography)-/,
 });
 
@@ -193,7 +193,8 @@ function normalizeTokenSource(source) {
 }
 
 function detectSourceFormat(filePath) {
-  if (path.extname(filePath).toLowerCase() === '.css') {
+  // .scss token files are read by the CSS collector too: custom properties plus Sass variables and maps.
+  if (['.css', '.scss'].includes(path.extname(filePath).toLowerCase())) {
     return 'css';
   }
 
@@ -237,23 +238,107 @@ function detectJsonTokenFormat(parsed) {
 
 function collectCssTokens(source, matchesKind) {
   const tokens = [];
-  const declarationPattern = /(--[\w-]+)\s*:\s*([^;{}]+)/g;
-  let match;
+  for (const declaration of customPropertyDeclarations(source)) {
+    if (matchesKind(declaration.token)) {
+      tokens.push(declaration);
+    }
+  }
+  for (const sassToken of collectScssTokens(source, matchesKind)) {
+    tokens.push({ ...sassToken, scope: 'root' });
+  }
+  return tokens;
+}
 
-  while ((match = declarationPattern.exec(source)) !== null) {
-    const token = match[1];
-    if (!matchesKind(token)) {
-      continue;
+const ROOT_SELECTOR = /^(?::root|html|:host|:(?:where|is)\(\s*(?::root|html)\s*\))$/i;
+// At-rules that only condition their contents; the enclosing selector still decides the scope.
+const TRANSPARENT_AT_RULES = new Set(['media', 'supports', 'layer', 'container', 'scope', 'document']);
+
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function scopeOfBlockHeaders(headers) {
+  for (let index = headers.length - 1; index >= 0; index -= 1) {
+    const header = headers[index];
+    if (header.startsWith('@')) {
+      const name = header.slice(1).match(/^[\w-]+/);
+      if (name && name[0].toLowerCase() === 'theme') return 'root';
+      if (name && TRANSPARENT_AT_RULES.has(name[0].toLowerCase())) continue;
+      return 'component';
     }
+    return header.split(',').every((selector) => ROOT_SELECTOR.test(selector.trim())) ? 'root' : 'component';
+  }
+  return 'root';
+}
 
-    tokens.push({
-      token,
-      value: match[2].trim(),
-    });
+/**
+ * Custom property declarations with the scope they are declared in: `root`
+ * for `:root`, `html`, `:host` and `@theme` blocks (through conditional
+ * at-rules), `component` for anything else. One pass over the source that
+ * skips comments and strings, so a brace in a comment cannot shift the
+ * scope; this is the text-side twin of scopeOfNode in scale-inference.js.
+ */
+function customPropertyDeclarations(source) {
+  const declarations = [];
+  const headers = [];
+  let headerStart = 0;
+  let index = 0;
+  const length = source.length;
+
+  while (index < length) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (char === '/' && next === '*') {
+      const end = source.indexOf('*/', index + 2);
+      index = end === -1 ? length : end + 2;
+      continue;
+    }
+    if (char === '/' && next === '/') {
+      const end = source.indexOf('\n', index);
+      index = end === -1 ? length : end;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      let end = index + 1;
+      while (end < length && source[end] !== char) end += source[end] === '\\' ? 2 : 1;
+      index = end + 1;
+      continue;
+    }
+    if (char === '{') {
+      if (source[index - 1] === '#') {
+        const end = source.indexOf('}', index);
+        index = end === -1 ? length : end + 1;
+        continue;
+      }
+      headers.push(stripComments(source.slice(headerStart, index)).trim().replace(/\s+/g, ' '));
+      headerStart = index + 1;
+      index += 1;
+      continue;
+    }
+    if (char === '}') {
+      headers.pop();
+      headerStart = index + 1;
+      index += 1;
+      continue;
+    }
+    if (char === ';') {
+      headerStart = index + 1;
+      index += 1;
+      continue;
+    }
+    if (char === '-' && next === '-' && !/[\w-]/.test(source[index - 1] || '')) {
+      const match = /^(--[\w-]+)\s*:\s*([^;{}]+)/.exec(source.slice(index));
+      if (match) {
+        declarations.push({ scope: scopeOfBlockHeaders(headers), token: match[1], value: match[2].trim() });
+        index += match[0].length;
+        continue;
+      }
+    }
+    index += 1;
   }
 
-  tokens.push(...collectScssTokens(source, matchesKind));
-  return tokens;
+  return declarations;
 }
 
 /**
@@ -283,16 +368,40 @@ function collectScssTokens(source, matchesKind) {
   };
 
   const tokens = [];
-  const push = (tokenName, value) => {
-    if (!value || !matchesKind(tokenName)) {
+  const push = (tokenName, value, force = false) => {
+    if (!value || (!force && !matchesKind(tokenName))) {
+      return;
+    }
+    const formatted = formatScssValue(value);
+    // A unitless number is a multiplier or a map index, not a length. Zero is fine.
+    if (/^-?\d*\.?\d+$/.test(formatted) && parseFloat(formatted) !== 0) {
       return;
     }
-    tokens.push({ token: tokenName, value: formatScssValue(value) });
+    tokens.push({ token: tokenName, value: formatted });
   };
+  // Namespaced maps such as GOV.UK's $govuk-spacing-points are only accepted
+  // for the spacing kind, and only when they hold a real ladder (issue #86).
+  const spacingKind = matchesKind('$spacing-probe');
 
   for (const [name, raw] of declarations) {
     const tokenName = `$${name}`;
     if (isScssMap(raw)) {
+      if (!matchesKind(tokenName) && spacingKind && NAMESPACED_SPACING_MAP.test(tokenName)) {
+        const entries = [];
+        walkScssMap(raw, [tokenName], (pathName, expression) => {
+          const value = evaluateScssExpression(expression, resolveVariable, new Set());
+          if (value) {
+            entries.push([pathName, value]);
+          }
+        });
+        const distinct = new Set(entries.map(([, value]) => formatScssValue(value)).filter((value) => /^-?\d*\.?\d+(?:px|rem|em)$/.test(value) && parseFloat(value) !== 0));
+        if (distinct.size >= MIN_NAMESPACED_MAP_LENGTHS) {
+          for (const [pathName, value] of entries) {
+            push(pathName, value, true);
+          }
+        }
+        continue;
+      }
       walkScssMap(raw, [tokenName], (pathName, expression) => {
         push(pathName, evaluateScssExpression(expression, resolveVariable, new Set()));
       });
@@ -304,6 +413,10 @@ function collectScssTokens(source, matchesKind) {
   return tokens;
 }
 
+/** `$<namespace>-spacing-points`, `$<ns>-space-scale`: one namespace segment before the anchor. */
+const NAMESPACED_SPACING_MAP = /^\$[a-z0-9]+-(?:space|spacing|spacer)s?(?:-|$)/i;
+const MIN_NAMESPACED_MAP_LENGTHS = 4;
+
 function stripScssComments(source) {
   return source
     .replace(/\/\*[\s\S]*?\*\//g, '')
@@ -381,7 +494,16 @@ function splitTopLevel(text, separator) {
   return parts;
 }
 
+// Real token maps nest two or three levels; generated or adversarial input can
+// nest without bound. Past these limits the value is treated like any other
+// expression the evaluator cannot handle: skipped, never guessed, never thrown.
+const MAX_SCSS_MAP_DEPTH = 16;
+const MAX_SCSS_EXPRESSION_DEPTH = 64;
+
 function walkScssMap(raw, pathSegments, visit) {
+  if (pathSegments.length > MAX_SCSS_MAP_DEPTH) {
+    return;
+  }
   const inner = raw.slice(1, -1);
   for (const entry of splitTopLevel(inner, ',')) {
     const pair = splitTopLevel(entry, ':');
@@ -454,7 +576,18 @@ function evaluateScssExpression(expression, resolveVariable, stack) {
     return { number: op === '+' ? left.number + right.number : left.number - right.number, unit: left.unit || right.unit };
   };
 
+  let depth = 0;
   const parsePrimary = () => {
+    if (depth > MAX_SCSS_EXPRESSION_DEPTH) return null;
+    depth += 1;
+    try {
+      return parsePrimaryInner();
+    } finally {
+      depth -= 1;
+    }
+  };
+
+  const parsePrimaryInner = () => {
     const token = next();
     if (!token) return null;
     if (token.type === 'number') return parseNumber(token.raw);
@@ -633,6 +766,7 @@ function extractTokenName(value) {
 function addDefinition(definitions, {
   baseFontSize,
   file,
+  scope = 'root',
   source,
   token,
   value,
@@ -640,12 +774,14 @@ function addDefinition(definitions, {
   const entry = definitions.get(token) || {
     files: new Set(),
     normalizedValues: new Set(),
+    scopes: new Set(),
     sources: new Set(),
     token,
     values: new Set(),
   };
 
   entry.files.add(file);
+  entry.scopes.add(scope);
   entry.sources.add(source);
   entry.values.add(String(value).trim());
 
@@ -719,7 +855,9 @@ module.exports = {
   VALID_TOKEN_KINDS,
   VALID_TOKEN_SOURCE_FORMATS,
   addDefinition,
+  collectCssTokens,
   collectScssTokens,
+  customPropertyDeclarations,
   createTokenKindMatcher,
   getNormalizedValueKeys,
   normalizeTokenKind,

package/src/{utils/value-utils.js → core/value-nodes.js}

@@ -1,11 +1,10 @@
 'use strict';
 
 const valueParser = require('postcss-value-parser');
-const stylelint = require('stylelint');
 const {
   MATH_FUNCTIONS,
   TRANSLATE_FUNCTIONS,
-} = require('./constants');
+} = require('./css-vocabulary');
 
 function propertyMatches(prop, patterns) {
   const normalized = prop.toLowerCase();
@@ -26,20 +25,6 @@ function isKeyword(value, ignoreValues) {
   return ignoreValues.includes(String(value).toLowerCase());
 }
 
-function createTokenRegex(tokenPattern, result, ruleName) {
-  try {
-    return new RegExp(tokenPattern);
-  } catch {
-    stylelint.utils.report({
-      message: `Invalid tokenPattern regex: ${tokenPattern}`,
-      result,
-      ruleName,
-    });
-
-    return /^--space-/;
-  }
-}
-
 function isTokenFunction(node, tokenFunctions, tokenRegex) {
   if (node.type !== 'function') {
     return false;
@@ -213,7 +198,6 @@ function declarationValueIndex(decl) {
 }
 
 module.exports = {
-  createTokenRegex,
   declarationValueIndex,
   isKeyword,
   isMathFunction,

package/src/eslint/rules/tailwind-class-use-motion-scale.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const { formatTime } = require('../../utils/time');
-const { createTailwindMotionAnalyzer } = require('../../utils/tailwind-motion-analysis');
+const { formatTime } = require('../../core/time');
+const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
 
 const RULE_NAME = 'tailwind-class-use-motion-scale';
 

package/src/eslint/rules/tailwind-class-use-scale.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const { formatLength } = require('../../utils/length');
-const { createTailwindClassAnalyzer } = require('../../utils/tailwind-class-analysis');
+const { formatLength } = require('../../core/length');
+const { createTailwindClassAnalyzer } = require('../../core/tailwind-class-analysis');
 
 const RULE_NAME = 'tailwind-class-use-scale';
 

package/src/rules/no-offscale-transform/index.js

@@ -3,33 +3,32 @@
 const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
+  fixedLengthValue,
   formatLength,
-  fromPx,
   isHairlineLength,
   nearestScaleValues,
-  normalizeScale,
-  normalizeScaleByUnit,
   numbersEqual,
   parseLengthToken,
   toPx,
-} = require('../../utils/length');
+} = require('../../core/length');
 const {
   buildScaleOptions,
-  resolvePropertyScale,
-  validateNoOffscaleTransformSecondaryOptions,
-} = require('../../utils/options');
+  createPropertyScaleResolver,
+} = require('../../core/options');
 const {
-  declarationValueIndex,
   isMathFunction,
   shouldLintMathArgument,
   walkRootValueNodes,
   walkTransformTranslateNodes,
-} = require('../../utils/value-utils');
+} = require('../../core/value-nodes');
 
 const {
-  DEFAULT_AUTO_TOKEN_PATTERN,
-  resolveAutoScale,
-} = require('../../utils/scale-inference');
+  withResolvedScale,
+} = require('../../core/scale-inference');
+
+const { validatePrimary, validateNoOffscaleTransformSecondaryOptions } = require('../validate');
+
+const { reportInvalidPreset, reportValueNode } = require('../report');
 
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
@@ -39,33 +38,9 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
     `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
 });
 
-function getFixedNodeValue(parsedLength, nearestPx, options) {
-  const unit = parsedLength.unit || 'px';
-  if (unit === '%' || !options.units.includes(unit)) {
-    return null;
-  }
-
-  const signedNearest = parsedLength.number < 0 ? -Math.abs(nearestPx) : nearestPx;
-
-  if (options.unitStrategy === 'exact') {
-    return formatLength(signedNearest, parsedLength.unit || 'px');
-  }
-
-  const converted = fromPx(signedNearest, unit, options.baseFontSize);
-
-  if (converted === null) {
-    return null;
-  }
-
-  return formatLength(converted, unit);
-}
-
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
-    const valid = stylelint.utils.validateOptions(result, ruleName, {
-      actual: primary,
-      possible: [true],
-    });
+    const valid = validatePrimary(result, ruleName, primary);
 
     if (!valid) {
       return;
@@ -81,43 +56,11 @@ const ruleFunction = (primary, secondaryOptions) => {
     }
 
     const options = buildScaleOptions(secondaryOptions);
-    if (options.invalidPreset) {
-      stylelint.utils.report({
-        message: messages.invalidPreset(options.invalidPreset, options.presetNames),
-        node: root,
-        result,
-        ruleName,
-      });
-    }
+    reportInvalidPreset(options, { message: messages.invalidPreset, result, root, ruleName });
 
-    if (options.scaleAuto) {
-      const inference = resolveAutoScale({
-        baseFontSize: options.baseFontSize,
-        root,
-        scaleSources: options.scaleSources,
-        tailwindConfigPath: options.tailwindConfigPath,
-        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
-      });
-      options.scale = inference.scale;
-      options.scaleInference = inference;
-    }
-
-    const scaleCache = new Map();
-    const getScaleStateForProperty = (prop) => {
-      const cached = scaleCache.get(prop);
-      if (cached) {
-        return cached;
-      }
-
-      const selectedScale = resolvePropertyScale(prop, options);
-      const next = {
-        scaleByUnit: normalizeScaleByUnit(selectedScale),
-        scalePx: normalizeScale(selectedScale, options.baseFontSize),
-      };
+    withResolvedScale(options, root);
 
-      scaleCache.set(prop, next);
-      return next;
-    };
+    const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     root.walkDecls((decl) => {
       const prop = decl.prop.toLowerCase();
@@ -130,30 +73,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       let changed = false;
 
       const report = (node, nearest, nearestUnit, fixedValue = null) => {
-        const index = declarationValueIndex(decl) + node.sourceIndex;
-        const endIndex = index + node.value.length;
-
-        const payload = {
-          endIndex,
-          index,
+        reportValueNode({
+          decl,
           message: messages.rejected(
             node.value,
             formatLength(nearest.lower, nearestUnit),
             formatLength(nearest.upper, nearestUnit),
           ),
-          node: decl,
+          node,
+          replacement: fixedValue,
           result,
           ruleName,
-        };
-
-        if (fixedValue) {
-          payload.fix = () => {
-            node.value = fixedValue;
-            return true;
-          };
-        }
-
-        stylelint.utils.report(payload);
+        });
       };
 
       const checkNode = (node) => {
@@ -205,7 +136,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
 
           const fixedValue = options.fixToScale
-            ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+            ? fixedLengthValue(parsedLength, nearest.nearest, options)
             : null;
 
           report(node, nearest, unit, fixedValue);
@@ -229,7 +160,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         }
 
         const fixedValue = options.fixToScale
-          ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+          ? fixedLengthValue(parsedLength, nearest.nearest, options)
           : null;
 
         report(node, nearest, 'px', fixedValue);

package/src/rules/prefer-token/index.js

@@ -5,20 +5,15 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   isHairlineLength,
-  normalizeScale,
-  normalizeScaleByUnit,
   numbersEqual,
   parseLengthToken,
   toPx,
-} = require('../../utils/length');
+} = require('../../core/length');
 const {
   buildTokenOptions,
-  resolvePropertyScale,
-  validatePreferTokenSecondaryOptions,
-} = require('../../utils/options');
+  createPropertyScaleResolver,
+} = require('../../core/options');
 const {
-  createTokenRegex,
-  declarationValueIndex,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -26,13 +21,15 @@ const {
   shouldLintMathArgument,
   walkRootValueNodes,
   walkTransformTranslateNodes,
-} = require('../../utils/value-utils');
-const { buildEffectiveTokenMap } = require('../../utils/token-map');
+} = require('../../core/value-nodes');
+const { buildEffectiveTokenMap } = require('../../core/token-map');
 
 const {
-  DEFAULT_AUTO_TOKEN_PATTERN,
-  resolveAutoScale,
-} = require('../../utils/scale-inference');
+  withResolvedScale,
+} = require('../../core/scale-inference');
+
+const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
+const { validatePrimary, validatePreferTokenSecondaryOptions } = require('../validate');
 
 const ruleName = 'rhythmguard/prefer-token';
 
@@ -90,10 +87,7 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
 
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
-    const valid = stylelint.utils.validateOptions(result, ruleName, {
-      actual: primary,
-      possible: [true],
-    });
+    const valid = validatePrimary(result, ruleName, primary);
 
     if (!valid) {
       return;
@@ -109,26 +103,9 @@ const ruleFunction = (primary, secondaryOptions) => {
     }
 
     const options = buildTokenOptions(secondaryOptions);
-    if (options.invalidPreset) {
-      stylelint.utils.report({
-        message: messages.invalidPreset(options.invalidPreset, options.presetNames),
-        node: root,
-        result,
-        ruleName,
-      });
-    }
+    reportInvalidPreset(options, { message: messages.invalidPreset, result, root, ruleName });
 
-    if (options.scaleAuto) {
-      const inference = resolveAutoScale({
-        baseFontSize: options.baseFontSize,
-        root,
-        scaleSources: options.scaleSources,
-        tailwindConfigPath: options.tailwindConfigPath,
-        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : DEFAULT_AUTO_TOKEN_PATTERN,
-      });
-      options.scale = inference.scale;
-      options.scaleInference = inference;
-    }
+    withResolvedScale(options, root);
 
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const tokenMap = buildEffectiveTokenMap({
@@ -137,23 +114,7 @@ const ruleFunction = (primary, secondaryOptions) => {
       tokenRegex,
     });
 
-    const scaleCache = new Map();
-
-    const getScaleStateForProperty = (prop) => {
-      const cached = scaleCache.get(prop);
-      if (cached) {
-        return cached;
-      }
-
-      const selectedScale = resolvePropertyScale(prop, options);
-      const next = {
-        scaleByUnit: normalizeScaleByUnit(selectedScale),
-        scalePx: normalizeScale(selectedScale, options.baseFontSize),
-      };
-
-      scaleCache.set(prop, next);
-      return next;
-    };
+    const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     root.walkDecls((decl) => {
       const prop = decl.prop.toLowerCase();
@@ -170,26 +131,7 @@ const ruleFunction = (primary, secondaryOptions) => {
       let changed = false;
 
       const reportNode = (node, replacement = null) => {
-        const index = declarationValueIndex(decl) + node.sourceIndex;
-        const endIndex = index + node.value.length;
-
-        const payload = {
-          endIndex,
-          index,
-          message: messages.rejected(node.value),
-          node: decl,
-          result,
-          ruleName,
-        };
-
-        if (replacement) {
-          payload.fix = () => {
-            node.value = replacement;
-            return true;
-          };
-        }
-
-        stylelint.utils.report(payload);
+        reportValueNode({ decl, message: messages.rejected(node.value), node, replacement, result, ruleName });
       };
 
       const checkWordNode = (node, context) => {