stylelint-plugin-rhythmguard 3.3.0 → 3.4.0

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

@@ -238,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';
+}
+
+/**
+ * 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];
 
-    tokens.push({
-      token,
-      value: match[2].trim(),
-    });
+    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;
 }
 
 /**
@@ -410,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, ':');
@@ -483,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);
@@ -662,6 +766,7 @@ function extractTokenName(value) {
 function addDefinition(definitions, {
   baseFontSize,
   file,
+  scope = 'root',
   source,
   token,
   value,
@@ -669,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());
 
@@ -748,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) => {

package/src/rules/report.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * The Stylelint side of a rule: everything that touches `stylelint.utils` or
+ * the PostCSS result lives here, so that src/core stays free of the framework
+ * and the same primitives can serve the ESLint plugin and the audit.
+ */
+const stylelint = require('stylelint');
+const { declarationValueIndex } = require('../core/value-nodes');
+
+/**
+ * Compile a user-supplied token pattern. An invalid pattern is reported once
+ * against the root and replaced with the historical default so the file still
+ * lints instead of throwing inside Stylelint.
+ */
+function createTokenRegex(tokenPattern, result, ruleName) {
+  try {
+    return new RegExp(tokenPattern);
+  } catch {
+    stylelint.utils.report({
+      message: `Invalid tokenPattern regex: ${tokenPattern}`,
+      result,
+      ruleName,
+    });
+
+    return /^--space-/;
+  }
+}
+
+/**
+ * Report one value node inside a declaration, positioned on the node rather
+ * than the whole declaration, with an optional fix. The default fix replaces
+ * the node's text; pass `fix` for anything else.
+ */
+function reportValueNode({ decl, fix = null, length = null, message, node, replacement = null, result, ruleName }) {
+  const index = declarationValueIndex(decl) + node.sourceIndex;
+  const payload = {
+    endIndex: index + (length === null ? node.value.length : length),
+    index,
+    message,
+    node: decl,
+    result,
+    ruleName,
+  };
+
+  if (fix) {
+    payload.fix = fix;
+  } else if (replacement) {
+    payload.fix = () => {
+      node.value = replacement;
+      return true;
+    };
+  }
+
+  stylelint.utils.report(payload);
+}
+
+/** A preset name the options did not recognise is reported once, on the root. */
+function reportInvalidPreset(options, { message, result, root, ruleName }) {
+  if (!options.invalidPreset) {
+    return;
+  }
+  stylelint.utils.report({
+    message: message(options.invalidPreset, options.presetNames),
+    node: root,
+    result,
+    ruleName,
+  });
+}
+
+module.exports = {
+  createTokenRegex,
+  reportInvalidPreset,
+  reportValueNode,
+};