stylelint-plugin-rhythmguard 3.5.0 → 3.7.0

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

@@ -1,5 +1,6 @@
 'use strict';
 
+const { MAX_NOTE_LENGTH, normalizeNote, withNote } = require('../../core/options');
 const { formatTime } = require('../../core/time');
 const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
 
@@ -51,7 +52,7 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
       ? formatTime(analysis.nearest.upper, 'ms')
       : 'n/a';
     context.report({
-      message: buildMessage(analysis, segment, lower, upper),
+      message: withNote(buildMessage(analysis, segment, lower, upper), analyzer.note),
       node,
       fix:
         fixedText && analysis.reason === 'duration'
@@ -95,13 +96,16 @@ module.exports = {
             },
             type: 'array',
           },
+          note: { maxLength: MAX_NOTE_LENGTH, minLength: 1, type: 'string' },
         },
         type: 'object',
       },
     ],
   },
   create(context) {
-    const analyzer = createTailwindMotionAnalyzer(context.options && context.options[0]);
+    const option = (context.options && context.options[0]) || {};
+    const analyzer = createTailwindMotionAnalyzer(option);
+    analyzer.note = normalizeNote(option.note);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {

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

@@ -1,7 +1,7 @@
 'use strict';
 
-const { formatLength } = require('../../core/length');
-const { createTailwindClassAnalyzer } = require('../../core/tailwind-class-analysis');
+const { MAX_NOTE_LENGTH, normalizeNote, withNote } = require('../../core/options');
+const { createTailwindClassAnalyzer, offScaleClassMessage } = require('../../core/tailwind-class-analysis');
 
 const RULE_NAME = 'tailwind-class-use-scale';
 
@@ -44,17 +44,8 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
     : null;
 
   for (const { analysis, segment } of findings) {
-    const lower = analysis.nearest
-      ? formatLength(analysis.nearest.lower, 'px')
-      : 'n/a';
-    const upper = analysis.nearest
-      ? formatLength(analysis.nearest.upper, 'px')
-      : 'n/a';
     context.report({
-      message:
-        analysis.reason === 'negative'
-          ? `Unexpected Tailwind arbitrary spacing value "${segment.token}". Negative values are disabled for this rule.`
-          : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values (nearest: ${lower} or ${upper}).`,
+      message: withNote(offScaleClassMessage(segment.token, analysis), analyzer.note),
       node,
       fix:
         fixedText && analysis.reason !== 'negative'
@@ -77,6 +68,7 @@ module.exports = {
         properties: {
           allowNegative: { type: 'boolean' },
           baseFontSize: { type: 'number' },
+          note: { maxLength: MAX_NOTE_LENGTH, minLength: 1, type: 'string' },
           scale: {
             items: {
               anyOf: [
@@ -86,6 +78,12 @@ module.exports = {
             },
             type: 'array',
           },
+          spacingUnit: {
+            anyOf: [
+              { exclusiveMinimum: true, minimum: 0, type: 'number' },
+              { enum: [false] },
+            ],
+          },
           units: {
             items: { type: 'string' },
             type: 'array',
@@ -96,7 +94,9 @@ module.exports = {
     ],
   },
   create(context) {
-    const analyzer = createTailwindClassAnalyzer(context.options && context.options[0]);
+    const option = (context.options && context.options[0]) || {};
+    const analyzer = createTailwindClassAnalyzer(option);
+    analyzer.note = normalizeNote(option.note);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {

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

@@ -3,7 +3,6 @@
 const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
-  fixedLengthValue,
   formatLength,
   isHairlineLength,
   nearestScaleValues,
@@ -23,19 +22,22 @@ const {
 } = require('../../core/value-nodes');
 
 const {
+  collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
 
 const { validatePrimary, validateNoOffscaleTransformSecondaryOptions } = require('../validate');
 
-const { reportInvalidPreset, reportValueNode } = require('../report');
+const { reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
+const { decisionFor, loadRcDecisions } = require('../../core/decisions');
+const { replacementFor, tokenHoldsNote, tokenIndexFromDefinitions } = require('../../core/token-index');
 
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper) =>
-    `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
+  rejected: (value, lower, upper, note = '') =>
+    `Unexpected transform translation value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
 const ruleFunction = (primary, secondaryOptions) => {
@@ -57,8 +59,20 @@ const ruleFunction = (primary, secondaryOptions) => {
 
     const options = buildScaleOptions(secondaryOptions);
     reportInvalidPreset(options, { message: messages.invalidPreset, result, root, ruleName });
+    try {
+      options.decisions = options.readDecisions ? loadRcDecisions(process.cwd(), { baseFontSize: options.baseFontSize }) : [];
+    } catch (error) {
+      reportProblem(error.message, { result, root, ruleName });
+      options.decisions = [];
+    }
 
     withResolvedScale(options, root);
+    if (options.fixWith === 'token') {
+      options.tokenIndex = tokenIndexFromDefinitions(
+        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex: new RegExp(options.tokenPattern) }),
+        options.baseFontSize,
+      );
+    }
 
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
@@ -79,6 +93,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             node.value,
             formatLength(nearest.lower, nearestUnit),
             formatLength(nearest.upper, nearestUnit),
+            [tokenHoldsNote(fixedValue, formatLength(nearest.nearest, nearestUnit)), options.note].filter(Boolean).join(' '),
           ),
           node,
           replacement: fixedValue,
@@ -117,6 +132,12 @@ const ruleFunction = (primary, secondaryOptions) => {
           return;
         }
 
+        const decidedPx = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+        const decision = decidedPx === null ? null : decisionFor(decidedPx, prop, options.decisions);
+        if (decision && (decision.decision === 'adopt' || decision.decision === 'allow')) {
+          return;
+        }
+
         if (options.unitStrategy === 'exact') {
           const unit = parsedLength.unit || 'px';
           const unitScale = scaleByUnit.get(unit);
@@ -136,7 +157,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
 
           const fixedValue = options.fixToScale
-            ? fixedLengthValue(parsedLength, nearest.nearest, options)
+            ? replacementFor(parsedLength, nearest.nearest, options)
             : null;
 
           report(node, nearest, unit, fixedValue);
@@ -160,7 +181,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         }
 
         const fixedValue = options.fixToScale
-          ? fixedLengthValue(parsedLength, nearest.nearest, options)
+          ? replacementFor(parsedLength, nearest.nearest, options)
           : null;
 
         report(node, nearest, 'px', fixedValue);

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

@@ -31,45 +31,34 @@ const {
 const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
 const { validatePrimary, validatePreferTokenSecondaryOptions } = require('../validate');
 
+const { negateReplacement } = 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) =>
-    `Unexpected raw scale value "${value}". Use design tokens for scale decisions.`,
+  rejected: (value, replacement = null, origin = null, note = '') =>
+    `Unexpected raw scale value "${value}". ${replacement
+      ? `Use ${replacement}${origin ? ` (${origin})` : ''}.`
+      : 'No known token holds this value; use the nearest token or add one.'}${note ? ` ${note}` : ''}`,
 });
 
 function applyNegativeToken(replacement, parsedLength) {
-  if (!replacement || parsedLength.number >= 0) {
-    return replacement;
-  }
-
-  if (replacement.startsWith('-')) {
-    return replacement;
-  }
-
-  if (
-    replacement.startsWith('var(') ||
-    replacement.startsWith('theme(') ||
-    replacement.startsWith('token(') ||
-    replacement.startsWith('$') ||
-    replacement.startsWith('@')
-  ) {
-    return `-${replacement}`;
-  }
-
-  return `calc(${replacement} * -1)`;
+  return !replacement || parsedLength.number >= 0 ? replacement : negateReplacement(replacement);
 }
 
+/** The token for a raw length, and the text the fix writes (negated when the literal is). */
 function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
+  const found = (token) => ({ replacement: applyNegativeToken(token, parsedLength), token });
+
   if (Object.prototype.hasOwnProperty.call(tokenMap, raw)) {
-    return applyNegativeToken(tokenMap[raw], parsedLength);
+    return found(tokenMap[raw]);
   }
 
   const absoluteRaw = formatLength(Math.abs(parsedLength.number), parsedLength.unit || 'px');
   if (Object.prototype.hasOwnProperty.call(tokenMap, absoluteRaw)) {
-    return applyNegativeToken(tokenMap[absoluteRaw], parsedLength);
+    return found(tokenMap[absoluteRaw]);
   }
 
   if (options.unitStrategy === 'convert') {
@@ -77,7 +66,7 @@ function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {
     if (absPx !== null) {
       const pxKey = `${absPx}px`;
       if (Object.prototype.hasOwnProperty.call(tokenMap, pxKey)) {
-        return applyNegativeToken(tokenMap[pxKey], parsedLength);
+        return found(tokenMap[pxKey]);
       }
     }
   }
@@ -108,8 +97,10 @@ const ruleFunction = (primary, secondaryOptions) => {
     withResolvedScale(options, root);
 
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
+    const origins = {};
     const tokenMap = buildEffectiveTokenMap({
       options,
+      origins,
       root,
       tokenRegex,
     });
@@ -130,8 +121,10 @@ const ruleFunction = (primary, secondaryOptions) => {
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
       let changed = false;
 
-      const reportNode = (node, replacement = null) => {
-        reportValueNode({ decl, message: messages.rejected(node.value), node, replacement, result, ruleName });
+      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 checkWordNode = (node, context) => {
@@ -197,9 +190,7 @@ const ruleFunction = (primary, secondaryOptions) => {
           }
         }
 
-        const replacement = resolveTokenReplacement(tokenMap, node.value, parsedLength, options);
-
-        reportNode(node, replacement);
+        reportNode(node, resolveTokenReplacement(tokenMap, node.value, parsedLength, options));
         return true;
       };
 

package/src/rules/report.js

@@ -68,8 +68,14 @@ function reportInvalidPreset(options, { message, result, root, ruleName }) {
   });
 }
 
+/** A configuration problem that is not about one node: reported once, on the root. */
+function reportProblem(message, { result, root, ruleName }) {
+  stylelint.utils.report({ message, node: root, result, ruleName });
+}
+
 module.exports = {
   createTokenRegex,
   reportInvalidPreset,
+  reportProblem,
   reportValueNode,
 };

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

@@ -20,6 +20,7 @@ const {
 
 const { reportValueNode } = require('../report');
 const { validatePrimary } = require('../validate');
+const { isNote, normalizeNote, withNote } = require('../../core/options');
 
 const ruleName = 'rhythmguard/use-motion-scale';
 const DURATION_PROPERTIES = new Set([
@@ -39,12 +40,12 @@ const EASING_PROPERTIES = new Set([
 const EASING_FUNCTIONS = new Set(['cubic-bezier', 'linear', 'steps']);
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
-  invalidDuration: (value) =>
-    `Unexpected negative motion duration "${value}". Use non-negative duration values.`,
-  rejectedDuration: (value, lower, upper) =>
-    `Unexpected motion duration "${value}". Use duration scale values (nearest: ${lower} or ${upper}).`,
-  rejectedEasing: (value) =>
-    `Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`,
+  invalidDuration: (value, note = '') =>
+    withNote(`Unexpected negative motion duration "${value}". Use non-negative duration values.`, note),
+  rejectedDuration: (value, lower, upper, note = '') =>
+    withNote(`Unexpected motion duration "${value}". Use duration scale values (nearest: ${lower} or ${upper}).`, note),
+  rejectedEasing: (value, note = '') =>
+    withNote(`Unexpected raw motion easing "${value}". Use motion tokens for easing decisions.`, note),
 });
 
 function isPlainObject(value) {
@@ -59,6 +60,7 @@ function buildOptions(rawOptions) {
     durationUnits: normalizeDurationUnits(options.durationUnits),
     easingTokenMap: isPlainObject(options.easingTokenMap) ? options.easingTokenMap : {},
     fixToScale: options.fixToScale !== false,
+    note: normalizeNote(options.note),
   };
 }
 
@@ -78,6 +80,7 @@ function validateSecondaryOptions(result, secondaryOptions) {
           typeof entry === 'string' && entry.trim().length > 0,
         )],
       fixToScale: [true, false],
+      note: [isNote],
     },
   });
 }
@@ -124,8 +127,9 @@ const ruleFunction = (primary, secondaryOptions) => {
               node.value,
               formatTime(nearest.lower, 'ms'),
               formatTime(nearest.upper, 'ms'),
+              options.note,
             )
-            : messages.invalidDuration(node.value),
+            : messages.invalidDuration(node.value, options.note),
           node,
           replacement: fixedValue,
           result,
@@ -146,7 +150,7 @@ const ruleFunction = (primary, secondaryOptions) => {
             }
             : null,
           length: source.length,
-          message: messages.rejectedEasing(source),
+          message: messages.rejectedEasing(source, options.note),
           node,
           result,
           ruleName,

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

@@ -3,7 +3,6 @@
 const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
-  fixedLengthValue,
   formatLength,
   isHairlineLength,
   nearestScaleValues,
@@ -27,10 +26,13 @@ const {
 
 const {
   autoScaleFallbackNote,
+  collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
 
-const { createTokenRegex, reportInvalidPreset, reportValueNode } = require('../report');
+const { createTokenRegex, reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
+const { decisionFor, loadRcDecisions } = require('../../core/decisions');
+const { replacementFor, tokenHoldsNote, tokenIndexFromDefinitions } = require('../../core/token-index');
 const { validatePrimary, validateUseScaleSecondaryOptions } = require('../validate');
 
 const ruleName = 'rhythmguard/use-scale';
@@ -42,6 +44,19 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
     `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
+/** Decisions from .rhythmguardrc.json; an invalid section is reported once and ignored. */
+function readDecisions(options, { result, root }) {
+  if (!options.readDecisions) {
+    return [];
+  }
+  try {
+    return loadRcDecisions(process.cwd(), { baseFontSize: options.baseFontSize });
+  } catch (error) {
+    reportProblem(error.message, { result, root, ruleName });
+    return [];
+  }
+}
+
 function checkLengthValue({
   decl,
   node,
@@ -90,6 +105,12 @@ function checkLengthValue({
     return false;
   }
 
+  const decidedPx = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
+  const decision = decidedPx === null ? null : decisionFor(decidedPx, decl.prop, options.decisions);
+  if (decision && (decision.decision === 'adopt' || decision.decision === 'allow')) {
+    return false;
+  }
+
   if (options.unitStrategy === 'exact') {
     const unit = parsedLength.unit || 'px';
     const unitScale = scaleByUnit.get(unit);
@@ -110,7 +131,7 @@ function checkLengthValue({
     }
 
     const fixedValue = options.fixToScale
-      ? fixedLengthValue(parsedLength, nearest.nearest, options)
+      ? replacementFor(parsedLength, nearest.nearest, options)
       : null;
 
     report(node.value, decl, node, nearest, fixedValue, unit);
@@ -134,7 +155,7 @@ function checkLengthValue({
   }
 
   const fixedValue = options.fixToScale
-    ? fixedLengthValue(parsedLength, nearest.nearest, options)
+    ? replacementFor(parsedLength, nearest.nearest, options)
     : null;
 
   report(node.value, decl, node, nearest, fixedValue, 'px');
@@ -160,19 +181,27 @@ const ruleFunction = (primary, secondaryOptions) => {
 
     const options = buildScaleOptions(secondaryOptions);
     reportInvalidPreset(options, { message: messages.invalidPreset, result, root, ruleName });
-
+    options.decisions = readDecisions(options, { result, root });
     withResolvedScale(options, root);
 
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
+    if (options.fixWith === 'token') {
+      options.tokenIndex = tokenIndexFromDefinitions(
+        collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex }),
+        options.baseFontSize,
+      );
+    }
+
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
     const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px') => {
       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),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, options.note].filter(Boolean).join(' ')),
         node,
         replacement: fixedValue,
         result,

package/types/audit.d.ts

@@ -98,6 +98,33 @@ export interface AuditBaselineComparison {
 
 export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
 
+export type AuditDecisionKind = "adopt" | "allow" | "snap" | "undecided";
+
+/** One entry of the `decisions` section of `.rhythmguardrc.json`. */
+export interface AuditDecision {
+  value: string;
+  decision: AuditDecisionKind;
+  /** For `adopt`: the token the value should become. */
+  as?: string;
+  /** For `allow`: property names or `prefix-*` patterns the allowance is limited to. */
+  properties?: string[];
+  reason?: string;
+}
+
+export interface AuditDecisionSummary {
+  adopt: number;
+  allow: number;
+  snap: number;
+  undecided: number;
+  suppressed: number;
+}
+
+/** One line of `rhythmguard audit --plan`: a decision entry with what the audit saw. */
+export interface AuditDecisionPlanEntry extends AuditDecision {
+  count: number;
+  nearest: string[];
+}
+
 export interface AuditScaleRejected {
   files?: string[];
   /** Why the inferred set was not accepted as a scale, for example "no common step". */
@@ -117,6 +144,8 @@ export interface AuditScale {
 }
 
 export interface AuditReport {
+  decisions?: AuditDecisionSummary | null;
+  decisionPlan?: AuditDecisionPlanEntry[];
   baseline?: AuditBaselineComparison | null;
   scale?: AuditScale | null;
   config?: string | null;
@@ -143,6 +172,8 @@ export interface AuditContractReport {
     scanScope: string;
   };
   contracts: {
+    /** Counts per decision kind and how many findings the decisions suppressed; null when the config has no decisions. */
+    decisions: AuditDecisionSummary | null;
     motion?: unknown;
     scale: {
       cleanliness?: unknown;

package/types/shared.d.ts

@@ -17,6 +17,12 @@ 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;
+  /** 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. */
+  decisions?: boolean;
+  /** A sentence of up to 200 characters appended to every finding, after the built-in text. */
+  note?: string;
   baseFontSize?: number;
   customScale?: ScaleValue[];
   includeMathFunctions?: boolean;