stylelint-plugin-rhythmguard 3.5.0 → 3.6.0

package/src/core/scale-inference.js

@@ -26,6 +26,8 @@ const FALLBACK_PRESET = 'rhythmic-4';
 const MIN_INFERRED_SCALE_LENGTH = 4;
 const RC_FILE = '.rhythmguardrc.json';
 
+const { cachedByFiles } = require('./fs-cache');
+
 const sourceCache = new Map();
 const TOKEN_PACKAGES = require('./token-packages.json').packages;
 
@@ -53,35 +55,6 @@ function readDirectDependencies(dir) {
  * installs are found by walking up; a stray global node_modules is never
  * consulted because the walk stops at the repository.
  */
-/**
- * Editors and pre-commit hooks lint one file at a time, and each lint asked
- * the filesystem the same questions: which package.json files sit between
- * cwd and the repository, what they declare, and whether a token package is
- * installed. The answers change only when one of those files changes, so
- * the result is cached per cwd and revalidated by mtime, which costs a stat
- * per file instead of a read, a JSON parse and a directory walk.
- */
-const discoveryCache = new Map();
-
-function fileStamp(file) {
-  try {
-    return fs.statSync(file).mtimeMs;
-  } catch {
-    return null;
-  }
-}
-
-function cachedByFiles(cacheKey, compute) {
-  const cached = discoveryCache.get(cacheKey);
-  if (cached && cached.stamps.every(([file, stamp]) => fileStamp(file) === stamp)) {
-    return cached.value;
-  }
-  const consulted = [];
-  const value = compute((file) => consulted.push([file, fileStamp(file)]));
-  discoveryCache.set(cacheKey, { stamps: consulted, value });
-  return value;
-}
-
 function projectRoots(cwd, consult = () => {}) {
   const roots = [];
   let current = path.resolve(cwd);
@@ -192,21 +165,27 @@ function cacheKey(sources) {
     .join('\n');
 }
 
-function scaleFromSources(sources, baseFontSize) {
+/** Parse token sources once per (sources, base font size, file mtimes). */
+function parseSourcesCached(sources, baseFontSize) {
   const normalized = sources.map((source) => normalizeSource(source, process.cwd())).filter(Boolean);
   if (normalized.length === 0) {
     return null;
   }
-
   const key = `${baseFontSize}\n${cacheKey(normalized)}`;
-  if (sourceCache.has(key)) {
-    return sourceCache.get(key);
+  if (!sourceCache.has(key)) {
+    sourceCache.set(key, parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' }));
   }
+  return sourceCache.get(key);
+}
 
-  const parsed = parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' });
+function scaleFromSources(sources, baseFontSize) {
+  const parsed = parseSourcesCached(sources, baseFontSize);
+  if (!parsed) {
+    return null;
+  }
   // scaleFromDefinitions also expands a bare Tailwind --spacing base into its multiples.
   const scale = scaleFromDefinitions(parsed.definitions, baseFontSize);
-  const outcome = scale
+  return scale
     ? {
       files: parsed.sources.map((source) => source.file),
       scale,
@@ -214,9 +193,26 @@ function scaleFromSources(sources, baseFontSize) {
       warnings: parsed.warnings,
     }
     : null;
+}
 
-  sourceCache.set(key, outcome);
-  return outcome;
+/**
+ * Every spacing token definition visible from a stylesheet, for fixes that
+ * write tokens: the stylesheet's own declarations, then `scaleSources`,
+ * `.rhythmguardrc.json` token sources and installed token packages. The same
+ * places scale inference reads, in the same order.
+ */
+function collectTokenDefinitions({ baseFontSize = 16, root, scaleSources = [], tokenRegex }) {
+  const definitions = root ? stylesheetDefinitions(root, tokenRegex, baseFontSize) : new Map();
+  const sources = [...scaleSources, ...rcTokenSources(process.cwd()), ...discoverTokenPackages(process.cwd())];
+  const parsed = parseSourcesCached(sources, baseFontSize);
+  if (parsed) {
+    for (const [token, definition] of parsed.definitions) {
+      if (!definitions.has(token)) {
+        definitions.set(token, definition);
+      }
+    }
+  }
+  return definitions;
 }
 
 /**
@@ -552,6 +548,7 @@ module.exports = {
   DEFAULT_AUTO_TOKEN_PATTERN,
   assessScale,
   autoScaleFallbackNote,
+  collectTokenDefinitions,
   discoverTokenPackages,
   inferScaleFromDefinitions,
   resolveAutoScale,

package/src/core/token-index.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { fixedLengthValue, numbersEqual, toPx } = require('./length');
+const { parseTokenValueLength } = require('./token-sources');
+
+/**
+ * Which token a fix may write for a length. Strict on purpose: the token must
+ * hold the same px value in the same unit as the literal being fixed, it must
+ * be a custom property (a Sass variable is not valid in CSS output), and it
+ * must be the only candidate. A fix that guesses a token is worse than a fix
+ * that writes a number, so anything ambiguous falls back to the literal.
+ */
+function tokenIndexFromDefinitions(definitions, baseFontSize = 16) {
+  const index = [];
+  for (const definition of definitions.values()) {
+    for (const raw of definition.values) {
+      const parsed = parseTokenValueLength(String(raw).trim());
+      if (!parsed) continue;
+      const unit = parsed.unit || 'px';
+      const px = toPx(Math.abs(parsed.number), unit, baseFontSize);
+      if (px === null || !Number.isFinite(px) || px === 0) continue;
+      index.push({ px, raw: String(raw).trim(), token: definition.token, unit });
+    }
+  }
+  return index;
+}
+
+function tokenForLength(index, px, unit) {
+  const wanted = unit || 'px';
+  const candidates = new Set();
+  for (const entry of index) {
+    if (entry.token.startsWith('--') && entry.unit === wanted && numbersEqual(entry.px, Math.abs(px))) {
+      candidates.add(entry.token);
+    }
+  }
+  if (candidates.size !== 1) {
+    return null;
+  }
+  return `var(${[...candidates][0]})`;
+}
+
+/** A negative token reference that is still valid where it is written. */
+function negateReplacement(replacement) {
+  if (!replacement || replacement.startsWith('-')) {
+    return replacement;
+  }
+  if (replacement.startsWith('$') || replacement.startsWith('@')) {
+    return `-${replacement}`;
+  }
+  return `calc(-1 * ${replacement})`;
+}
+
+/**
+ * The replacement text a length rule writes: the matching token when the
+ * options ask for one and exactly one qualifies, otherwise the literal.
+ */
+function replacementFor(parsedLength, nearestPx, options) {
+  if (options.fixWith === 'token' && options.tokenIndex) {
+    const token = tokenForLength(options.tokenIndex, nearestPx, parsedLength.unit || 'px');
+    if (token) {
+      return parsedLength.number < 0 ? negateReplacement(token) : token;
+    }
+  }
+  return fixedLengthValue(parsedLength, nearestPx, options);
+}
+
+module.exports = {
+  negateReplacement,
+  replacementFor,
+  tokenForLength,
+  tokenIndexFromDefinitions,
+};

package/src/core/token-sources.js

@@ -792,8 +792,9 @@ function addDefinition(definitions, {
   definitions.set(token, entry);
 }
 
-const CALC_LENGTH_TIMES_VAR = /^calc\(\s*(-?[\d.]+(?:px|rem|em)?)\s*\*\s*var\([^()]*\)\s*\)$/i;
-const CALC_VAR_TIMES_LENGTH = /^calc\(\s*var\([^()]*\)\s*\*\s*(-?[\d.]+(?:px|rem|em)?)\s*\)$/i;
+// The factor must carry a unit: `calc(4px * var(--scaling))` is a length, `calc(var(--x) * 2)` is a multiplier.
+const CALC_LENGTH_TIMES_VAR = /^calc\(\s*(-?[\d.]+(?:px|rem|em))\s*\*\s*var\([^()]*\)\s*\)$/i;
+const CALC_VAR_TIMES_LENGTH = /^calc\(\s*var\([^()]*\)\s*\*\s*(-?[\d.]+(?:px|rem|em))\s*\)$/i;
 
 /**
  * Parse the length a token value carries. Accepts plain lengths and the

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,12 +22,15 @@ 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, tokenIndexFromDefinitions } = require('../../core/token-index');
 
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
@@ -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);
 
@@ -117,6 +131,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 +156,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 +180,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,6 +31,8 @@ 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, {
@@ -41,25 +43,7 @@ const messages = stylelint.utils.ruleMessages(ruleName, {
 });
 
 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);
 }
 
 function resolveTokenReplacement(tokenMap, raw, parsedLength, options) {

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-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, 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,10 +181,17 @@ 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);
 

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,10 @@ 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;
   baseFontSize?: number;
   customScale?: ScaleValue[];
   includeMathFunctions?: boolean;