stylelint-plugin-rhythmguard 3.8.0 → 3.10.0

package/src/core/token-sources.js

@@ -123,7 +123,7 @@ function parseTokenSources({
       continue;
     }
 
-    let tokens = [];
+    let tokens;
     const matchesSource = normalizedSource.tokenPattern
       ? createPatternMatcher(normalizedSource.tokenPattern, matchesKind)
       : matchesKind;
@@ -428,7 +428,7 @@ function createScssVariableResolver(source, fallback = () => null) {
     if (stack.has(name)) {
       return null;
     }
-    let value = null;
+    let value;
     if (declarations.has(name)) {
       stack.add(name);
       const raw = declarations.get(name);

package/src/core/value-nodes.js

@@ -191,6 +191,55 @@ function shouldLintMathArgument(context, options) {
   return true;
 }
 
+const BOUND_FUNCTIONS = new Set(['clamp', 'min', 'max']);
+
+function isBoundFunction(node) {
+  return node.type === 'function' && BOUND_FUNCTIONS.has(node.value.toLowerCase());
+}
+
+function splitArguments(nodes) {
+  const args = [[]];
+  for (const node of nodes) {
+    if (node.type === 'div' && node.value === ',') {
+      args.push([]);
+      continue;
+    }
+    if (node.type !== 'space' && node.type !== 'comment') {
+      args[args.length - 1].push(node);
+    }
+  }
+  return args;
+}
+
+/**
+ * The static bounds of a fluid value (issue #203): the minimum and maximum of
+ * `clamp(MIN, VAL, MAX)` and every argument of `min()` and `max()`. A bound
+ * counts only when it is one word, a length literal; the preferred value of
+ * clamp(), an expression, or a var() is fluid by design and left alone. A
+ * bound that is itself min(), max() or clamp() is followed.
+ */
+function collectMathBounds(fnNode) {
+  const name = fnNode.value.toLowerCase();
+  const args = splitArguments(fnNode.nodes);
+  const positioned = name === 'clamp'
+    ? (args.length === 3 ? [[args[0], 'clamp() minimum'], [args[2], 'clamp() maximum']] : [])
+    : args.map((arg) => [arg, `${name}() argument`]);
+
+  const bounds = [];
+  for (const [arg, position] of positioned) {
+    if (arg.length !== 1) {
+      continue;
+    }
+    const [node] = arg;
+    if (node.type === 'word') {
+      bounds.push({ node, position });
+    } else if (isBoundFunction(node)) {
+      bounds.push(...collectMathBounds(node));
+    }
+  }
+  return bounds;
+}
+
 function declarationValueIndex(decl) {
   const declarationText = decl.toString();
   const idx = declarationText.indexOf(decl.value);
@@ -198,7 +247,9 @@ function declarationValueIndex(decl) {
 }
 
 module.exports = {
+  collectMathBounds,
   declarationValueIndex,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,

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

@@ -69,7 +69,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     withResolvedScale(options, root);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex: new RegExp(options.tokenPattern) }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex: new RegExp(options.tokenPattern),
+        }),
         options.baseFontSize,
       );
     }
@@ -157,7 +163,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
 
           const fixedValue = options.fixToScale
-            ? replacementFor(parsedLength, nearest.nearest, options)
+            ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
             : null;
 
           report(node, nearest, unit, fixedValue);
@@ -181,7 +187,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         }
 
         const fixedValue = options.fixToScale
-          ? replacementFor(parsedLength, nearest.nearest, options)
+          ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
           : null;
 
         report(node, nearest, 'px', fixedValue);

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

@@ -14,6 +14,8 @@ const {
   createPropertyScaleResolver,
 } = require('../../core/options');
 const {
+  collectMathBounds,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -25,25 +27,40 @@ const {
 const { buildEffectiveTokenMap } = require('../../core/token-map');
 
 const {
+  collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
 
 const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
 const { validatePrimary, validatePreferTokenSecondaryOptions } = require('../validate');
 
-const { negateReplacement } = require('../../core/token-index');
+const {
+  negateReplacement,
+  tokenFitsProperty,
+  tokenIndexFromDefinitions,
+  tokensForLength,
+} = require('../../core/token-index');
 
 const ruleName = 'rhythmguard/prefer-token';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, replacement = null, origin = null, note = '') =>
-    `Unexpected raw scale value "${value}". ${replacement
+  rejected: (value, replacement = null, origin = null, note = '', candidates = [], position = null) =>
+    `Unexpected raw ${position || 'scale value'} "${value}". ${replacement
       ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
-      : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
+      : candidates.length > 1
+        ? `Use one of the tokens that hold it: ${listTokens(candidates)}.`
+        : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
 });
 
+function listTokens(tokens) {
+  const references = tokens.map((token) => `var(${token})`);
+  return references.length > 1
+    ? `${references.slice(0, -1).join(', ')} or ${references[references.length - 1]}`
+    : references.join('');
+}
+
 function applyNegativeToken(replacement, parsedLength) {
   return !replacement || parsedLength.number >= 0 ? replacement : negateReplacement(replacement);
 }
@@ -74,6 +91,36 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
   return null;
 }
 
+/**
+ * The tokens use-scale's `fixWith: "token"` would see: the stylesheet,
+ * `scaleSources`, `.rhythmguardrc.json` token sources and installed token
+ * packages, filtered to the property's kind. One same-unit token is a fix; a
+ * token in another unit, or several tokens, are named but never written.
+ */
+function resolveFromIndex(tokenIndex, parsedLength, prop, options) {
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', options.baseFontSize);
+  if (px === null || tokenIndex.length === 0) {
+    return { candidates: [] };
+  }
+  const unit = parsedLength.unit || 'px';
+  const sameUnit = tokensForLength(tokenIndex, px, unit, { prop });
+  const candidates = sameUnit.length > 0 || options.unitStrategy !== 'convert'
+    ? sameUnit
+    : tokensForLength(tokenIndex, px, unit, { anyUnit: true, prop });
+  if (candidates.length !== 1) {
+    return { candidates };
+  }
+  const token = `var(${candidates[0]})`;
+  const entry = tokenIndex.find((item) => item.token === candidates[0]);
+  return {
+    candidates,
+    fixable: sameUnit.length === 1,
+    origin: entry ? entry.file : null,
+    replacement: applyNegativeToken(token, parsedLength),
+    token,
+  };
+}
+
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
     const valid = validatePrimary(result, ruleName, primary);
@@ -105,6 +152,17 @@ const ruleFunction = (primary, secondaryOptions) => {
       tokenRegex,
     });
 
+    const tokenIndex = tokenIndexFromDefinitions(
+      collectTokenDefinitions({
+        baseFontSize: options.baseFontSize,
+        root,
+        scaleSources: options.scaleSources,
+        tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+        tokenRegex,
+      }),
+      options.baseFontSize,
+    );
+
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     root.walkDecls((decl) => {
@@ -121,18 +179,31 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, resolved = null) => {
-        const replacement = resolved ? resolved.replacement : null;
-        const origin = resolved ? origins[resolved.token] || null : null;
-        reportValueNode({ decl, message: messages.rejected(node.value, replacement, origin, options.note), node, replacement, result, ruleName });
+      const reportNode = (node, parsedLength, position = null) => {
+        const mapped = resolveTokenReplacement(tokenMap, node.value, parsedLength, options);
+        if (mapped && tokenFitsProperty(mapped.token, prop)) {
+          const origin = origins[mapped.token] || null;
+          reportValueNode({ decl, message: messages.rejected(node.value, mapped.replacement, origin, options.note, [], position), node, replacement: mapped.replacement, result, ruleName });
+          return;
+        }
+        const indexed = resolveFromIndex(tokenIndex, parsedLength, prop, options);
+        const named = indexed.replacement || null;
+        reportValueNode({
+          decl,
+          message: messages.rejected(node.value, named, indexed.origin || null, options.note, indexed.candidates, position),
+          node,
+          replacement: indexed.fixable ? named : null,
+          result,
+          ruleName,
+        });
       };
 
-      const checkWordNode = (node, context) => {
+      const checkWordNode = (node, context, position = null) => {
         if (isKeyword(node.value, options.ignoreValues)) {
           return false;
         }
 
-        if (!shouldLintMathArgument(context, options)) {
+        if (!position && !shouldLintMathArgument(context, options)) {
           return false;
         }
 
@@ -190,7 +261,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        reportNode(node, resolveTokenReplacement(tokenMap, node.value, parsedLength, options));
+        reportNode(node, parsedLength, position);
         return true;
       };
 
@@ -216,12 +287,22 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         });
       } else {
+        const checkedBounds = new Set();
         walkRootValueNodes(parsed, (node, context) => {
           if (node.type === 'function') {
             if (isTokenFunction(node, options.tokenFunctions, tokenRegex)) {
               return true;
             }
 
+            if (options.checkMathBounds && isBoundFunction(node)) {
+              for (const bound of collectMathBounds(node)) {
+                if (!checkedBounds.has(bound.node)) {
+                  checkedBounds.add(bound.node);
+                  changed = checkWordNode(bound.node, null, bound.position) || changed;
+                }
+              }
+            }
+
             if (isMathFunction(node.value) && !options.enforceInsideMathFunctions) {
               return true;
             }
@@ -229,7 +310,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             return false;
           }
 
-          if (node.type !== 'word') {
+          if (node.type !== 'word' || checkedBounds.has(node)) {
             return false;
           }
 

package/src/rules/use-scale/index.js

@@ -15,6 +15,8 @@ const {
   createPropertyScaleResolver,
 } = require('../../core/options');
 const {
+  collectMathBounds,
+  isBoundFunction,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -41,10 +43,20 @@ const ruleName = 'rhythmguard/use-scale';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper, note = '') =>
-    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
+  rejected: (value, lower, upper, note = '', position = null, aside = '', group = null) =>
+    `Unexpected off-scale ${position ? `${position} "${value}"${aside}` : `value "${value}"`}. Use ${group ? `${group} ` : ''}scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
+/** " (16.8px)" after a bound written in rem or em, so the reader sees what was compared. */
+function pxAside(value, baseFontSize) {
+  const parsed = parseLengthToken(value);
+  if (!parsed || !parsed.unit || parsed.unit === 'px' || parsed.unit === '%') {
+    return '';
+  }
+  const px = toPx(Math.abs(parsed.number), parsed.unit, baseFontSize);
+  return px === null ? '' : ` (${formatLength(parsed.number < 0 ? -px : px, 'px')})`;
+}
+
 /** Decisions from .rhythmguardrc.json; an invalid section is reported once and ignored. */
 function readDecisions(options, { result, root }) {
   if (!options.readDecisions) {
@@ -136,7 +148,7 @@ function checkLengthValue({
     }
 
     const fixedValue = options.fixToScale && fixable
-      ? replacementFor(parsedLength, nearest.nearest, options)
+      ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
       : null;
 
     report(node.value, decl, node, nearest, fixedValue, unit, evaluated ? evaluatedNote(evaluated, options) : '');
@@ -160,7 +172,7 @@ function checkLengthValue({
   }
 
   const fixedValue = options.fixToScale && fixable
-    ? replacementFor(parsedLength, nearest.nearest, options)
+    ? replacementFor(parsedLength, nearest.nearest, options, decl.prop)
     : null;
 
   report(node.value, decl, node, nearest, fixedValue, 'px', evaluated ? evaluatedNote(evaluated, options) : '');
@@ -239,7 +251,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     if (options.fixWith === 'token') {
       options.tokenIndex = tokenIndexFromDefinitions(
-        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex }),
+        collectTokenDefinitions({
+          baseFontSize: options.baseFontSize,
+          root,
+          scaleSources: options.scaleSources,
+          tokenPattern: options.tokenPatternExplicit ? options.tokenPattern : null,
+          tokenRegex,
+        }),
         options.baseFontSize,
       );
     }
@@ -247,13 +265,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
-    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '') => {
+    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '', position = null) => {
       const lower = nearest ? formatLength(nearest.lower, nearestUnit) : 'n/a';
       const upper = nearest ? formatLength(nearest.upper, nearestUnit) : 'n/a';
       const tokenNote = nearest ? tokenHoldsNote(fixedValue, formatLength(nearest.nearest, nearestUnit)) : '';
       reportValueNode({
         decl,
-        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, extraNote, options.note].filter(Boolean).join(' ')),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, extraNote, options.note].filter(Boolean).join(' '), position, position ? pxAside(value, options.baseFontSize) : '', getScaleStateForProperty(decl.prop.toLowerCase()).group),
         node,
         replacement: fixedValue,
         result,
@@ -336,6 +354,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         });
       } else {
+        const checkedBounds = new Set();
         walkRootValueNodes(parsed, (node, context) => {
 
           if (node.type === 'function') {
@@ -343,6 +362,20 @@ const ruleFunction = (primary, secondaryOptions) => {
               return true;
             }
 
+            if (options.checkMathBounds && isBoundFunction(node)) {
+              for (const bound of collectMathBounds(node)) {
+                if (checkedBounds.has(bound.node)) {
+                  continue;
+                }
+                checkedBounds.add(bound.node);
+                if (isKeyword(bound.node.value, options.ignoreValues)) {
+                  continue;
+                }
+                const boundReport = (value, d, n, nearest, fixed, unit, extra) => report(value, d, n, nearest, fixed, unit, extra, bound.position);
+                changed = checkLengthValue({ decl, node: bound.node, options, report: boundReport, scaleByUnit, scalePx }) || changed;
+              }
+            }
+
             if (
               isMathFunction(node.value) &&
               !options.enforceInsideMathFunctions
@@ -353,7 +386,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             return false;
           }
 
-          if (node.type !== 'word') {
+          if (node.type !== 'word' || checkedBounds.has(node)) {
             return false;
           }
 

package/types/audit.d.ts

@@ -32,7 +32,11 @@ export interface AuditOptions {
   format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github" | "badge";
   ignorePath?: string;
   ignorePatterns?: string[];
+  /** Check clamp() bounds and min()/max() arguments against the scale (equivalent to `--check-math-bounds`). */
+  checkMathBounds?: boolean;
   includeMotion?: boolean;
+  /** A scale per property group (`spacing`, `radius`, `size`, `typography`): values, a preset name or "auto". Each group named is also checked. */
+  scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", Array<number | string> | string | { preset?: string; scale?: Array<number | string>; customScale?: Array<number | string> }>>;
   maxFindings?: number;
   minCleanliness?: number;
   /** Skip config discovery entirely (equivalent to `--no-config`). */
@@ -68,6 +72,8 @@ export interface AuditScanned {
   scssFiles?: number;
   /** .scss files found but not audited because postcss-scss is not installed. */
   scssSkipped?: number;
+  /** Stylesheets Stylelint skipped because the project's own .stylelintignore excludes them. */
+  stylelintIgnored?: number;
   templateFiles: number;
   totalFiles?: number;
   [key: string]: unknown;

package/types/shared.d.ts

@@ -17,6 +17,8 @@ export interface ScaleSource {
 export interface RhythmguardRuleOptions {
   /** Exempt non-zero lengths of one CSS pixel or less (1px, -1px, 0.5px, 0.0625rem). Default true. */
   allowHairlines?: boolean;
+  /** Check the static bounds of fluid values: the clamp() minimum and maximum and each length argument of min() and max(). Default false; the preferred value of clamp() is never checked. */
+  checkMathBounds?: boolean;
   /** What autofix writes: the nearest literal (default) or, with "token", `var(--name)` when exactly one custom property holds that value in the same unit. */
   fixWith?: "value" | "token";
   /** Read the `decisions` section of `.rhythmguardrc.json` (default true). The audit sets false and applies decisions itself. */
@@ -34,6 +36,12 @@ export interface RhythmguardRuleOptions {
    * properties, then `tailwindConfigPath`, falling back to the `rhythmic-4` preset.
    */
   scale?: ScaleValue[] | "auto";
+  /**
+   * A scale per property group, used before `scale` and after `propertyScales`: values, a
+   * preset name, or `"auto"` to infer the group's scale from its tokens (`--font-size-*` and
+   * `--text-*` for typography, `--radius-*` for radius). Findings then name the group's scale.
+   */
+  scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", ScaleValue[] | string | { preset?: string; scale?: ScaleValue[]; customScale?: ScaleValue[] }>>;
   /** Token files consulted first when `scale` is `"auto"`. */
   scaleSources?: Array<string | ScaleSource>;
   /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */