stylelint-plugin-rhythmguard 3.2.0 → 3.4.0

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,
+};

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

@@ -5,11 +5,10 @@ const valueParser = require('postcss-value-parser');
 const {
   nearestScaleValues,
   numbersEqual,
-} = require('../../utils/length');
+} = require('../../core/length');
 const {
-  declarationValueIndex,
   walkRootValueNodes,
-} = require('../../utils/value-utils');
+} = require('../../core/value-nodes');
 const {
   formatTime,
   fromMs,
@@ -17,7 +16,10 @@ const {
   normalizeDurationUnits,
   parseTimeToken,
   toMs,
-} = require('../../utils/time');
+} = require('../../core/time');
+
+const { reportValueNode } = require('../report');
+const { validatePrimary } = require('../validate');
 
 const ruleName = 'rhythmguard/use-motion-scale';
 const DURATION_PROPERTIES = new Set([
@@ -99,12 +101,7 @@ function functionToString(node) {
 
 const ruleFunction = (primary, secondaryOptions) => {
   return (root, result) => {
-    const valid = stylelint.utils.validateOptions(result, ruleName, {
-      actual: primary,
-      possible: [true],
-    });
-
-    if (!valid || !validateSecondaryOptions(result, secondaryOptions)) {
+    if (!validatePrimary(result, ruleName, primary) || !validateSecondaryOptions(result, secondaryOptions)) {
       return;
     }
 
@@ -120,10 +117,8 @@ const ruleFunction = (primary, secondaryOptions) => {
       let changed = false;
 
       const reportDuration = (node, nearest, fixedValue = null) => {
-        const index = declarationValueIndex(decl) + node.sourceIndex;
-        const payload = {
-          endIndex: index + node.value.length,
-          index,
+        reportValueNode({
+          decl,
           message: nearest
             ? messages.rejectedDuration(
               node.value,
@@ -131,43 +126,31 @@ const ruleFunction = (primary, secondaryOptions) => {
               formatTime(nearest.upper, 'ms'),
             )
             : messages.invalidDuration(node.value),
-          node: decl,
+          node,
+          replacement: fixedValue,
           result,
           ruleName,
-        };
-
-        if (fixedValue) {
-          payload.fix = () => {
-            node.value = fixedValue;
-            return true;
-          };
-        }
-
-        stylelint.utils.report(payload);
+        });
       };
 
       const reportEasing = (node, replacement = null) => {
         const source = functionToString(node);
-        const index = declarationValueIndex(decl) + node.sourceIndex;
-        const payload = {
-          endIndex: index + source.length,
-          index,
+        reportValueNode({
+          decl,
+          fix: replacement
+            ? () => {
+              node.type = 'word';
+              node.value = replacement;
+              delete node.nodes;
+              return true;
+            }
+            : null,
+          length: source.length,
           message: messages.rejectedEasing(source),
-          node: decl,
+          node,
           result,
           ruleName,
-        };
-
-        if (replacement) {
-          payload.fix = () => {
-            node.type = 'word';
-            node.value = replacement;
-            delete node.nodes;
-            return true;
-          };
-        }
-
-        stylelint.utils.report(payload);
+        });
       };
 
       walkRootValueNodes(parsed, (node) => {

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

@@ -3,24 +3,19 @@
 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,
-  validateUseScaleSecondaryOptions,
-} = require('../../utils/options');
+  createPropertyScaleResolver,
+} = require('../../core/options');
 const {
-  createTokenRegex,
-  declarationValueIndex,
   isKeyword,
   isMathFunction,
   isTokenFunction,
@@ -28,13 +23,15 @@ const {
   shouldLintMathArgument,
   walkRootValueNodes,
   walkTransformTranslateNodes,
-} = require('../../utils/value-utils');
+} = require('../../core/value-nodes');
 
 const {
-  DEFAULT_AUTO_TOKEN_PATTERN,
   autoScaleFallbackNote,
-  resolveAutoScale,
-} = require('../../utils/scale-inference');
+  withResolvedScale,
+} = require('../../core/scale-inference');
+
+const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
+const { validatePrimary, validateUseScaleSecondaryOptions } = require('../validate');
 
 const ruleName = 'rhythmguard/use-scale';
 
@@ -45,28 +42,6 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
     `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
-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);
-}
-
 function checkLengthValue({
   decl,
   node,
@@ -135,7 +110,7 @@ function checkLengthValue({
     }
 
     const fixedValue = options.fixToScale
-      ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+      ? fixedLengthValue(parsedLength, nearest.nearest, options)
       : null;
 
     report(node.value, decl, node, nearest, fixedValue, unit);
@@ -159,7 +134,7 @@ function checkLengthValue({
   }
 
   const fixedValue = options.fixToScale
-    ? getFixedNodeValue(parsedLength, nearest.nearest, options)
+    ? fixedLengthValue(parsedLength, nearest.nearest, options)
     : null;
 
   report(node.value, decl, node, nearest, fixedValue, 'px');
@@ -168,10 +143,7 @@ function checkLengthValue({
 
 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;
@@ -187,71 +159,26 @@ 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;
-    }
+    withResolvedScale(options, root);
 
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
-    const scaleCache = new Map();
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
-
-    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);
 
     const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px') => {
-      const index = declarationValueIndex(decl) + node.sourceIndex;
-      const endIndex = index + node.value.length;
       const lower = nearest ? formatLength(nearest.lower, nearestUnit) : 'n/a';
       const upper = nearest ? formatLength(nearest.upper, nearestUnit) : 'n/a';
-
-      const payload = {
-        endIndex,
-        index,
+      reportValueNode({
+        decl,
         message: messages.rejected(value, lower, upper, fallbackNote),
-        node: decl,
+        node,
+        replacement: fixedValue,
         result,
         ruleName,
-      };
-
-      if (fixedValue) {
-        payload.fix = () => {
-          node.value = fixedValue;
-          return true;
-        };
-      }
-
+      });
       fallbackNote = '';
-      stylelint.utils.report(payload);
     };
 
     root.walkDecls((decl) => {

package/src/rules/validate.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * Secondary-option validation through Stylelint's `validateOptions`, plus the
+ * shape checks it cannot express (arrays and objects). The schemas themselves
+ * live in src/core/options.js and know nothing about Stylelint.
+ */
+const stylelint = require('stylelint');
+const {
+  NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS,
+  NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA,
+  PREFER_TOKEN_POSSIBLE_OPTIONS,
+  PREFER_TOKEN_VALIDATION_SCHEMA,
+  USE_SCALE_POSSIBLE_OPTIONS,
+  USE_SCALE_VALIDATION_SCHEMA,
+  isPlainObject,
+} = require('../core/options');
+
+function validateSecondaryOptionShapes(result, ruleName, secondaryOptions, schema) {
+  if (secondaryOptions === undefined || secondaryOptions === null) {
+    return true;
+  }
+
+  if (!isPlainObject(secondaryOptions)) {
+    return true;
+  }
+
+  let valid = true;
+
+  for (const [optionName, descriptor] of Object.entries(schema)) {
+    const optionValue = secondaryOptions[optionName];
+    if (optionValue === undefined) {
+      continue;
+    }
+
+    const literalAllowed = Array.isArray(descriptor.allowLiterals)
+      && descriptor.allowLiterals.includes(optionValue);
+
+    if (descriptor.expectsArray && !Array.isArray(optionValue) && !literalAllowed) {
+      valid = false;
+      result.warn(
+        `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
+        { stylelintType: 'invalidOption' },
+      );
+      result.stylelint.stylelintError = true;
+      continue;
+    }
+
+    if (descriptor.expectsObject && !isPlainObject(optionValue)) {
+      valid = false;
+      result.warn(
+        `Invalid value ${stringifyOptionValue(optionValue)} for option "${optionName}" of rule "${ruleName}"`,
+        { stylelintType: 'invalidOption' },
+      );
+      result.stylelint.stylelintError = true;
+    }
+  }
+
+  return valid;
+}
+
+function stringifyOptionValue(value) {
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+
+  return `"${JSON.stringify(value)}"`;
+}
+
+function validateSecondaryOptions({
+  result,
+  ruleName,
+  secondaryOptions,
+  schema,
+  possibleOptionMap,
+}) {
+  const validOptions = stylelint.utils.validateOptions(result, ruleName, {
+    actual: secondaryOptions,
+    optional: true,
+    possible: possibleOptionMap,
+  });
+  const validShapes = validateSecondaryOptionShapes(
+    result,
+    ruleName,
+    secondaryOptions,
+    schema,
+  );
+
+  return validOptions && validShapes;
+}
+
+function validateUseScaleSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: USE_SCALE_VALIDATION_SCHEMA,
+    possibleOptionMap: USE_SCALE_POSSIBLE_OPTIONS,
+  });
+}
+
+function validateNoOffscaleTransformSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA,
+    possibleOptionMap: NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS,
+  });
+}
+
+function validatePreferTokenSecondaryOptions(result, ruleName, secondaryOptions) {
+  return validateSecondaryOptions({
+    result,
+    ruleName,
+    secondaryOptions,
+    schema: PREFER_TOKEN_VALIDATION_SCHEMA,
+    possibleOptionMap: PREFER_TOKEN_POSSIBLE_OPTIONS,
+  });
+}
+
+/** Every Rhythmguard rule takes `true` as its primary option and nothing else. */
+function validatePrimary(result, ruleName, primary) {
+  return stylelint.utils.validateOptions(result, ruleName, { actual: primary, possible: [true] });
+}
+
+module.exports = {
+  validatePrimary,
+  validateNoOffscaleTransformSecondaryOptions,
+  validatePreferTokenSecondaryOptions,
+  validateUseScaleSecondaryOptions,
+};

package/types/audit.d.ts

@@ -98,9 +98,19 @@ export interface AuditBaselineComparison {
 
 export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
 
+export interface AuditScaleRejected {
+  files?: string[];
+  /** Why the inferred set was not accepted as a scale, for example "no common step". */
+  reasons: string[];
+  source: AuditScaleSource;
+  values: Array<number | string>;
+}
+
 export interface AuditScale {
   /** Files the scale was derived from (token sources or scanned stylesheets). Empty for explicit, default and fallback. */
   files: string[];
+  /** Present when `source` is "fallback" because an inferred scale failed the plausibility check. */
+  rejected?: AuditScaleRejected | null;
   source: AuditScaleSource;
   tokenCount: number;
   values: Array<number | string>;
@@ -139,6 +149,7 @@ export interface AuditContractReport {
       files: string[];
       offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
+      rejected: AuditScaleRejected | null;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;
       values: Array<number | string> | null;