stylelint-plugin-rhythmguard 3.5.0 → 3.7.0

package/src/core/fs-cache.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const fs = require('node:fs');
+
+/**
+ * Editors and pre-commit hooks lint one file at a time, and each lint asks the
+ * filesystem the same questions: which package.json files sit between cwd and
+ * the repository, what .rhythmguardrc.json says, whether a token package is
+ * installed. The answers change only when one of those files changes, so a
+ * result is cached per key and revalidated by the mtime of every file the
+ * computation consulted: a stat per file instead of a read, a parse and a walk.
+ */
+const cache = new Map();
+
+function fileStamp(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function cachedByFiles(cacheKey, compute) {
+  const cached = cache.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)]));
+  cache.set(cacheKey, { stamps: consulted, value });
+  return value;
+}
+
+module.exports = {
+  cachedByFiles,
+};

package/src/core/length.js

@@ -205,6 +205,7 @@ function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy,
 module.exports = {
   fixedLengthValue,
   formatLength,
+  formatNumber,
   fromPx,
   isHairlineLength,
   nearestScaleValues,

package/src/core/options.js

@@ -54,6 +54,22 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
+const MAX_NOTE_LENGTH = 200;
+
+/** A `note` is appended to every finding, so it stays a sentence: non-empty, at most 200 characters. */
+function isNote(value) {
+  return isNonEmptyString(value) && value.trim().length <= MAX_NOTE_LENGTH;
+}
+
+function normalizeNote(value) {
+  return isNote(value) ? value.trim() : '';
+}
+
+/** The message with the configured note after it, or the message alone. */
+function withNote(message, note) {
+  return note ? `${message} ${note}` : message;
+}
+
 function isSupportedUnit(value) {
   if (!isNonEmptyString(value)) {
     return false;
@@ -62,6 +78,10 @@ function isSupportedUnit(value) {
   return SUPPORTED_SCALE_UNITS.has(value.trim().toLowerCase());
 }
 
+function isFixWith(value) {
+  return value === 'value' || value === 'token';
+}
+
 function isUnitStrategy(value) {
   return value === 'convert' || value === 'exact';
 }
@@ -359,6 +379,9 @@ function resolveUnits(options) {
 }
 
 const SCALE_VALIDATION_SCHEMA = Object.freeze({
+  decisions: Object.freeze({
+    entryValidator: isBoolean,
+  }),
   allowHairlines: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -378,6 +401,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
   enforceInsideMathFunctions: Object.freeze({
     entryValidator: isBoolean,
   }),
+  fixWith: Object.freeze({
+    entryValidator: isFixWith,
+  }),
   fixToScale: Object.freeze({
     entryValidator: isBoolean,
   }),
@@ -389,6 +415,9 @@ const SCALE_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isMathFunctionArgumentMap,
     expectsObject: true,
   }),
+  note: Object.freeze({
+    entryValidator: isNote,
+  }),
   preset: Object.freeze({
     entryValidator: isNonEmptyString,
   }),
@@ -473,6 +502,9 @@ const PREFER_TOKEN_VALIDATION_SCHEMA = Object.freeze({
     entryValidator: isMathFunctionArgumentMap,
     expectsObject: true,
   }),
+  note: Object.freeze({
+    entryValidator: isNote,
+  }),
   preset: Object.freeze({
     entryValidator: isNonEmptyString,
   }),
@@ -545,6 +577,7 @@ function buildScaleOptions(rawOptions) {
 
   return {
     allowHairlines: options.allowHairlines !== false,
+    readDecisions: options.decisions !== false,
     allowNegative: options.allowNegative !== false,
     allowPercentages: options.allowPercentages !== false,
     baseFontSize:
@@ -555,12 +588,14 @@ function buildScaleOptions(rawOptions) {
         : 16,
     enforceInsideMathFunctions: options.enforceInsideMathFunctions === true,
     fixToScale: options.fixToScale !== false,
+    fixWith: options.fixWith === 'token' ? 'token' : 'value',
     ignoreMathFunctionArguments: normalizeMathFunctionArgumentMap(options.ignoreMathFunctionArguments),
     ignoreValues: Array.isArray(options.ignoreValues)
       ? options.ignoreValues.map((value) => String(value).toLowerCase())
       : DEFAULT_IGNORE_KEYWORDS,
     invalidPreset: scaleSelection.invalidPreset,
     mathFunctionArguments: normalizeMathFunctionArgumentMap(options.mathFunctionArguments),
+    note: normalizeNote(options.note),
     preset: scaleSelection.selectedPreset,
     presetNames: listScalePresetNames(),
     properties: resolvePropertyPatterns(options),
@@ -606,6 +641,7 @@ function buildTokenOptions(rawOptions) {
       : DEFAULT_IGNORE_KEYWORDS,
     invalidPreset: scaleSelection.invalidPreset,
     mathFunctionArguments: normalizeMathFunctionArgumentMap(options.mathFunctionArguments),
+    note: normalizeNote(options.note),
     preset: scaleSelection.selectedPreset,
     presetNames: listScalePresetNames(),
     properties: resolvePropertyPatterns(options),
@@ -689,6 +725,10 @@ function resolvePropertyScale(prop, options) {
 }
 
 module.exports = {
+  MAX_NOTE_LENGTH,
+  isNote,
+  normalizeNote,
+  withNote,
   NO_OFFSCALE_TRANSFORM_POSSIBLE_OPTIONS,
   NO_OFFSCALE_TRANSFORM_VALIDATION_SCHEMA,
   PREFER_TOKEN_POSSIBLE_OPTIONS,

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/tailwind-class-analysis.js

@@ -2,6 +2,7 @@
 
 const {
   formatLength,
+  formatNumber,
   nearestScaleValues,
   normalizeScale,
   numbersEqual,
@@ -11,6 +12,9 @@ const {
 
 const DEFAULT_SCALE = [0, 4, 8, 12, 16, 24, 32];
 const DEFAULT_UNITS = ['px', 'rem', 'em'];
+// Tailwind's numeric spacing utilities are multiples of one unit: `--spacing`
+// (0.25rem, 4px) in v4, and the same 4px step in the v3 default scale.
+const DEFAULT_SPACING_UNIT_PX = 4;
 
 const ARBITRARY_SPACING_CLASS = /^(?<utility>-?(?:m(?:[trblxy])?|p(?:[trblxy])?|gap(?:-[xy])?|space-[xy]|inset(?:-[xy])?|top|right|bottom|left|translate-[xy]|scroll-(?:m|p)(?:[trblxy])?))-\[(?<rawValue>[^\]]+)\]$/;
 
@@ -24,6 +28,11 @@ function normalizeTailwindClassOptions(option = {}) {
         ? option.baseFontSize
         : 16,
     scale: Array.isArray(option.scale) ? option.scale : DEFAULT_SCALE,
+    spacingUnit: option.spacingUnit === false
+      ? null
+      : typeof option.spacingUnit === 'number' && Number.isFinite(option.spacingUnit) && option.spacingUnit > 0
+        ? option.spacingUnit
+        : DEFAULT_SPACING_UNIT_PX,
     units: Array.isArray(option.units)
       ? option.units.map((unit) => String(unit).toLowerCase())
       : DEFAULT_UNITS,
@@ -121,6 +130,26 @@ function hasInvalidVariantPrefix(prefix) {
   return false;
 }
 
+/**
+ * The utility class Tailwind generates for a px value, or null when the value
+ * is not a quarter step of the spacing unit (v4 generates any quarter step;
+ * v3 generates the quarter steps of its default scale). `p-3` for 12px on a
+ * 4px unit; `-m-3` when the class or the value is negative.
+ */
+function utilityClassFor(utility, px, negative, spacingUnit) {
+  if (!spacingUnit) {
+    return null;
+  }
+  const steps = Math.abs(px) / spacingUnit;
+  const quarters = steps * 4;
+  if (Math.abs(quarters - Math.round(quarters)) > 1e-9) {
+    return null;
+  }
+  const name = utility.startsWith('-') ? utility.slice(1) : utility;
+  const sign = negative && steps !== 0 ? '-' : '';
+  return `${sign}${name}-${formatNumber(Math.round(quarters) / 4)}`;
+}
+
 function analyzeClassToken(token, options, scalePx) {
   const parsedToken = parseClassToken(token);
   if (parsedToken.prefix && hasInvalidVariantPrefix(parsedToken.prefix)) {
@@ -175,13 +204,22 @@ function analyzeClassToken(token, options, scalePx) {
     ? signedNearest
     : signedNearest / options.baseFontSize;
 
+  const negative = match.groups.utility.startsWith('-') || parsedLength.number < 0;
+  const wrap = (candidate) =>
+    `${parsedToken.prefix}${parsedToken.leadingImportant}${candidate}${parsedToken.trailingImportant}`;
+  const utilityFix = utilityClassFor(match.groups.utility, nearest.nearest, negative, options.spacingUnit);
+  const lowerUtility = utilityClassFor(match.groups.utility, nearest.lower, negative, options.spacingUnit);
+  const upperUtility = utilityClassFor(match.groups.utility, nearest.upper, negative, options.spacingUnit);
+
   const replacementValue = formatLength(replacementNumber, parsedLength.unit);
-  const fixedCandidate = parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
-  const fixedToken = `${parsedToken.prefix}${parsedToken.leadingImportant}${fixedCandidate}${parsedToken.trailingImportant}`;
+  const fixedCandidate = utilityFix || parsedToken.candidate.replace(match.groups.rawValue, replacementValue);
 
   return {
-    fixedToken,
+    fixedToken: wrap(fixedCandidate),
     nearest,
+    // The utility classes for the two nearest steps, when both are quarter
+    // steps of the spacing unit; messages name these instead of px values.
+    nearestUtilities: lowerUtility && upperUtility ? { lower: lowerUtility, upper: upperUtility } : null,
     parsedLength,
     reason: 'off-scale',
     rawValue: match.groups.rawValue,
@@ -214,8 +252,26 @@ function createTailwindClassAnalyzer(option = {}) {
   };
 }
 
+/**
+ * The message text for an off-scale class: the two nearest utility classes
+ * with their px values when the unit makes them, the px steps otherwise.
+ */
+function offScaleClassMessage(token, analysis) {
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary spacing value "${token}". Negative values are disabled for this rule.`;
+  }
+  const lowerPx = analysis.nearest ? formatLength(analysis.nearest.lower, 'px') : 'n/a';
+  const upperPx = analysis.nearest ? formatLength(analysis.nearest.upper, 'px') : 'n/a';
+  if (analysis.nearestUtilities) {
+    const { lower, upper } = analysis.nearestUtilities;
+    return `Unexpected Tailwind arbitrary spacing value "${token}". Use "${lower}" (${lowerPx}) or "${upper}" (${upperPx}).`;
+  }
+  return `Unexpected Tailwind arbitrary spacing value "${token}". Use scale values (nearest: ${lowerPx} or ${upperPx}).`;
+}
+
 module.exports = {
   createTailwindClassAnalyzer,
   findClassSegments,
   normalizeTailwindClassOptions,
+  offScaleClassMessage,
 };

package/src/core/token-index.js

@@ -0,0 +1,82 @@
+'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);
+}
+
+/**
+ * The sentence a length rule appends when its fix writes a token: which token
+ * holds the snapped value. Empty when the replacement is a literal.
+ */
+function tokenHoldsNote(replacement, formattedNearest) {
+  const match = typeof replacement === 'string' ? replacement.match(/var\(--[^)]+\)/) : null;
+  return match ? `${match[0]} holds ${formattedNearest}.` : '';
+}
+
+module.exports = {
+  negateReplacement,
+  replacementFor,
+  tokenHoldsNote,
+  tokenForLength,
+  tokenIndexFromDefinitions,
+};

package/src/core/token-map.js

@@ -40,7 +40,19 @@ function normalizeTokenReference(tokenReference) {
   return `var(--${trimmed})`;
 }
 
-function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
+/**
+ * Where a token came from, for messages: the path relative to the working
+ * directory when it is inside it, the absolute path otherwise.
+ */
+function displayOrigin(file) {
+  if (!file) {
+    return null;
+  }
+  const relative = path.relative(process.cwd(), file);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
+}
+
+function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize, origins = null, origin = null) {
   if (typeof rawLength !== 'string') {
     return;
   }
@@ -55,6 +67,10 @@ function addLengthValueMapping(map, rawLength, tokenReference, baseFontSize) {
     return;
   }
 
+  if (origins && origin && !origins[token]) {
+    origins[token] = origin;
+  }
+
   const absolute = Math.abs(parsed.number);
   const normalizedRaw = formatLength(absolute, parsed.unit || 'px');
   map[normalizedRaw] = token;
@@ -81,7 +97,7 @@ function mergeExplicitTokenMap(target, source) {
   return target;
 }
 
-function walkTokenGroup(map, group, prefix, baseFontSize) {
+function walkTokenGroup(map, group, prefix, baseFontSize, origins, origin) {
   for (const [key, value] of Object.entries(group)) {
     const tokenName = `${prefix}-${key}`;
 
@@ -91,24 +107,25 @@ function walkTokenGroup(map, group, prefix, baseFontSize) {
 
     // Leaf node with $value (DTCG)
     if (typeof value.$value === 'string') {
-      addLengthValueMapping(map, value.$value, tokenName, baseFontSize);
+      addLengthValueMapping(map, value.$value, tokenName, baseFontSize, origins, origin);
       continue;
     }
 
     // Leaf node with value (Style Dictionary)
     if (typeof value.value === 'string') {
-      addLengthValueMapping(map, value.value, tokenName, baseFontSize);
+      addLengthValueMapping(map, value.value, tokenName, baseFontSize, origins, origin);
       continue;
     }
 
-    // Nested group — recurse deeper
-    walkTokenGroup(map, value, tokenName, baseFontSize);
+    // Nested group: recurse deeper
+    walkTokenGroup(map, value, tokenName, baseFontSize, origins, origin);
   }
 }
 
 function mergeTokenMapFromFile({
   baseFontSize,
   currentMap,
+  origins = null,
   tokenMapFile,
 }) {
   if (!tokenMapFile) {
@@ -134,6 +151,7 @@ function mergeTokenMapFromFile({
   const nextMap = {
     ...currentMap,
   };
+  const origin = displayOrigin(resolvedPath);
 
   for (const [entryKey, entryValue] of Object.entries(parsed)) {
     if (typeof entryValue === 'string') {
@@ -142,36 +160,39 @@ function mergeTokenMapFromFile({
 
       if (keyAsLength) {
         nextMap[entryKey] = entryValue;
+        if (origins && !origins[entryValue]) {
+          origins[entryValue] = origin;
+        }
         continue;
       }
 
       if (valueAsLength) {
-        addLengthValueMapping(nextMap, entryValue, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
       }
 
       continue;
     }
 
     if (typeof entryValue === 'number') {
-      addLengthValueMapping(nextMap, `${entryValue}px`, entryKey, baseFontSize);
+      addLengthValueMapping(nextMap, `${entryValue}px`, entryKey, baseFontSize, origins, origin);
       continue;
     }
 
     if (isPlainObject(entryValue)) {
       // Style Dictionary format: { value: "16px" }
       if (typeof entryValue.value === 'string') {
-        addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue.value, entryKey, baseFontSize, origins, origin);
         continue;
       }
 
       // W3C DTCG format: { $value: "16px", $type: "dimension" }
       if (typeof entryValue.$value === 'string') {
-        addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize);
+        addLengthValueMapping(nextMap, entryValue.$value, entryKey, baseFontSize, origins, origin);
         continue;
       }
 
-      // Nested group — recurse (e.g. { spacing: { 4: { $value: "16px" } } })
-      walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize);
+      // Nested group: recurse (e.g. { spacing: { 4: { $value: "16px" } } })
+      walkTokenGroup(nextMap, entryValue, entryKey, baseFontSize, origins, origin);
     }
   }
 
@@ -181,12 +202,14 @@ function mergeTokenMapFromFile({
 function mergeTokenMapFromCssCustomProperties({
   baseFontSize,
   currentMap,
+  origins = null,
   root,
   tokenRegex,
 }) {
   const nextMap = {
     ...currentMap,
   };
+  const origin = displayOrigin(root && root.source && root.source.input ? root.source.input.file : null);
 
   root.walkDecls((decl) => {
     const prop = decl.prop.toLowerCase();
@@ -203,7 +226,7 @@ function mergeTokenMapFromCssCustomProperties({
       return;
     }
 
-    addLengthValueMapping(nextMap, decl.value, `var(${decl.prop})`, baseFontSize);
+    addLengthValueMapping(nextMap, decl.value, `var(${decl.prop})`, baseFontSize, origins, origin);
   });
 
   return nextMap;
@@ -321,6 +344,7 @@ function loadTailwindSpacing(resolvedPath) {
 
 function mergeTokenMapFromTailwindSpacing({
   currentMap,
+  origins = null,
   tailwindConfigPath,
 }) {
   if (!tailwindConfigPath) {
@@ -354,13 +378,23 @@ function mergeTokenMapFromTailwindSpacing({
     const absolute = Math.abs(parsed.number);
     const normalizedRaw = formatLength(absolute, parsed.unit || 'px');
     nextMap[normalizedRaw] = `theme(spacing.${key})`;
+    if (origins && !origins[nextMap[normalizedRaw]]) {
+      origins[nextMap[normalizedRaw]] = displayOrigin(resolvedPath);
+    }
   }
 
   return nextMap;
 }
 
+/**
+ * The raw-length to token-reference map a rule fixes with. Pass `origins` to
+ * also learn where each token reference came from (the token map file, the
+ * stylesheet, the Tailwind config), keyed by the reference; an explicit
+ * `tokenMap` entry has no origin.
+ */
 function buildEffectiveTokenMap({
   options,
+  origins = null,
   root,
   tokenRegex,
 }) {
@@ -370,6 +404,7 @@ function buildEffectiveTokenMap({
     tokenMap = mergeTokenMapFromFile({
       baseFontSize: options.baseFontSize,
       currentMap: tokenMap,
+      origins,
       tokenMapFile: options.tokenMapFile,
     });
   }
@@ -378,6 +413,7 @@ function buildEffectiveTokenMap({
     tokenMap = mergeTokenMapFromCssCustomProperties({
       baseFontSize: options.baseFontSize,
       currentMap: tokenMap,
+      origins,
       root,
       tokenRegex,
     });
@@ -386,6 +422,7 @@ function buildEffectiveTokenMap({
   if (options.tokenMapFromTailwindSpacing && options.tailwindConfigPath) {
     tokenMap = mergeTokenMapFromTailwindSpacing({
       currentMap: tokenMap,
+      origins,
       tailwindConfigPath: options.tailwindConfigPath,
     });
   }

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