stylelint-plugin-rhythmguard 3.3.0 → 3.4.0

package/src/audit/scan/templates.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Findings from template files: Tailwind class strings inside string literals,
+ * for spacing and (opt-in) motion, with line and column recovered from offsets.
+ */
+const fs = require('node:fs');
+const { formatLength } = require('../../core/length');
+const { createTailwindClassAnalyzer } = require('../../core/tailwind-class-analysis');
+const { createTailwindMotionAnalyzer } = require('../../core/tailwind-motion-analysis');
+const { formatTime } = require('../../core/time');
+const {
+  formatPath,
+} = require('../shared');
+
+function collectTailwindFindings(templateFiles, options) {
+  const analyzer = createTailwindClassAnalyzer(options);
+  const findings = [];
+
+  for (const filePath of templateFiles) {
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lineStarts = getLineStarts(source);
+
+    for (const literal of findStringLiterals(source)) {
+      for (const { analysis, segment } of analyzer.analyzeClassString(literal.value)) {
+        const position = offsetToLineColumn(lineStarts, literal.valueStart + segment.start);
+        findings.push({
+          column: position.column,
+          file: formatPath(filePath),
+          fixedToken: analysis.fixedToken,
+          line: position.line,
+          nearest: analysis.nearest
+            ? {
+              lower: formatLength(analysis.nearest.lower, 'px'),
+              upper: formatLength(analysis.nearest.upper, 'px'),
+            }
+            : null,
+          rawValue: analysis.rawValue,
+          rule: 'rhythmguard-tailwind/tailwind-class-use-scale',
+          text: 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.`,
+          token: segment.token,
+          type: 'tailwind-arbitrary-spacing',
+          utility: analysis.utility,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function collectTailwindMotionFindings(templateFiles, options) {
+  if (!options.includeMotion) {
+    return [];
+  }
+
+  const analyzer = createTailwindMotionAnalyzer(options);
+  const findings = [];
+
+  for (const filePath of templateFiles) {
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lineStarts = getLineStarts(source);
+
+    for (const literal of findStringLiterals(source)) {
+      for (const { analysis, segment } of analyzer.analyzeClassString(literal.value)) {
+        const position = offsetToLineColumn(lineStarts, literal.valueStart + segment.start);
+        findings.push({
+          column: position.column,
+          file: formatPath(filePath),
+          fixedToken: analysis.fixedToken,
+          line: position.line,
+          nearest: analysis.nearest
+            ? {
+              lower: formatTime(analysis.nearest.lower, 'ms'),
+              upper: formatTime(analysis.nearest.upper, 'ms'),
+            }
+            : null,
+          rawValue: analysis.rawValue,
+          rule: 'rhythmguard-tailwind/tailwind-class-use-motion-scale',
+          text: buildTailwindMotionFindingText(segment.token, analysis),
+          token: segment.token,
+          type: analysis.reason === 'easing'
+            ? 'tailwind-motion-easing'
+            : 'tailwind-motion-duration',
+          utility: analysis.utility,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function buildTailwindMotionFindingText(token, analysis) {
+  if (analysis.reason === 'easing') {
+    return `Unexpected Tailwind arbitrary motion easing "${token}". Use motion tokens for easing decisions.`;
+  }
+
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary motion duration "${token}". Use non-negative duration values.`;
+  }
+
+  return `Unexpected Tailwind arbitrary motion duration "${token}". Use duration scale values.`;
+}
+
+function findStringLiterals(source) {
+  const literals = [];
+  const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
+  let match;
+
+  while ((match = literalPattern.exec(source)) !== null) {
+    literals.push({
+      quote: match[1],
+      value: match[2],
+      valueStart: match.index + 1,
+    });
+  }
+
+  return literals;
+}
+
+function getLineStarts(source) {
+  const starts = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === '\n') {
+      starts.push(index + 1);
+    }
+  }
+
+  return starts;
+}
+
+function offsetToLineColumn(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lineStarts[mid] <= offset) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  const lineIndex = Math.max(0, high);
+  return {
+    column: offset - lineStarts[lineIndex] + 1,
+    line: lineIndex + 1,
+  };
+}
+
+module.exports = {
+  buildTailwindMotionFindingText,
+  collectTailwindFindings,
+  collectTailwindMotionFindings,
+  findStringLiterals,
+  getLineStarts,
+  offsetToLineColumn,
+};

package/src/cli/doctor.js

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { normalizeTokenSourceFormat } = require('../utils/token-sources');
+const { normalizeTokenSourceFormat } = require('../core/token-sources');
 
 const cwd = process.cwd();
 let issues = 0;

package/src/cli/quickstart.js

@@ -14,7 +14,7 @@ const path = require('node:path');
 
 const { createAuditReport } = require('../audit/report');
 const { detect } = require('./init');
-const { discoverTokenPackages } = require('../utils/scale-inference');
+const { discoverTokenPackages } = require('../core/scale-inference');
 
 const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
 const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];

package/src/{utils → core}/length.js

@@ -182,7 +182,28 @@ function nearestScaleValues(target, scale) {
   };
 }
 
+/**
+ * The replacement text for an off-scale length, or null when the value's unit
+ * is not one the rule may rewrite. Keeps the sign, and with the `exact` unit
+ * strategy keeps the unit as written instead of converting through px.
+ */
+function fixedLengthValue(parsedLength, nearestPx, { baseFontSize, unitStrategy, units }) {
+  const unit = parsedLength.unit || 'px';
+  if (unit === '%' || !units.includes(unit)) {
+    return null;
+  }
+
+  const signedNearest = parsedLength.number < 0 ? -Math.abs(nearestPx) : nearestPx;
+  if (unitStrategy === 'exact') {
+    return formatLength(signedNearest, unit);
+  }
+
+  const converted = fromPx(signedNearest, unit, baseFontSize);
+  return converted === null ? null : formatLength(converted, unit);
+}
+
 module.exports = {
+  fixedLengthValue,
   formatLength,
   fromPx,
   isHairlineLength,

package/src/{utils → core}/options.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const stylelint = require('stylelint');
+const { normalizeScale, normalizeScaleByUnit } = require('./length');
+
 const { all: knownCssProperties = [] } = require('known-css-properties');
 const {
   DEFAULT_IGNORE_KEYWORDS,
@@ -10,7 +11,7 @@ const {
   PROPERTY_GROUP_PATTERNS,
   SPACING_PROPERTY_PATTERNS,
   SUPPORTED_SCALE_UNITS,
-} = require('./constants');
+} = require('./css-vocabulary');
 const { parseLengthToken } = require('./length');
 const {
   getScalePreset,
@@ -236,57 +237,6 @@ function isPropertyScaleMap(value) {
   });
 }
 
-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 buildPossibleOptionMap(schema) {
   return Object.fromEntries(
     Object.entries(schema).map(([optionName, descriptor]) => [
@@ -296,28 +246,6 @@ function buildPossibleOptionMap(schema) {
   );
 }
 
-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 normalizePropertyGroups(rawGroups) {
   const source = Array.isArray(rawGroups) && rawGroups.length > 0
     ? rawGroups
@@ -713,6 +641,27 @@ function buildTokenOptions(rawOptions) {
   };
 }
 
+/**
+ * Per-property scale lookup with a cache, because a stylesheet repeats the
+ * same few properties thousands of times and normalising a scale is not free.
+ */
+function createPropertyScaleResolver(options) {
+  const cache = new Map();
+  return (prop) => {
+    const cached = cache.get(prop);
+    if (cached) {
+      return cached;
+    }
+    const selectedScale = resolvePropertyScale(prop, options);
+    const state = {
+      scaleByUnit: normalizeScaleByUnit(selectedScale),
+      scalePx: normalizeScale(selectedScale, options.baseFontSize),
+    };
+    cache.set(prop, state);
+    return state;
+  };
+}
+
 function resolvePropertyScale(prop, options) {
   if (!Array.isArray(options.propertyScaleOverrides)) {
     return options.scale;
@@ -739,41 +688,16 @@ function resolvePropertyScale(prop, options) {
   return options.scale;
 }
 
-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,
-  });
-}
-
 module.exports = {
+  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,
   buildScaleOptions,
   buildTokenOptions,
+  createPropertyScaleResolver,
+  isPlainObject,
   resolvePropertyScale,
-  validateNoOffscaleTransformSecondaryOptions,
-  validatePreferTokenSecondaryOptions,
-  validateUseScaleSecondaryOptions,
 };

package/src/{utils → core}/scale-inference.js

@@ -5,7 +5,13 @@ const path = require('node:path');
 
 const { parseLengthToken, toPx } = require('./length');
 const { buildEffectiveTokenMap } = require('./token-map');
-const { collectScssTokens, createTokenKindMatcher, parseTokenSources } = require('./token-sources');
+const {
+  addDefinition,
+  collectScssTokens,
+  createTokenKindMatcher,
+  parseTokenSources,
+  parseTokenValueLength,
+} = require('./token-sources');
 const { getScalePreset } = require('../presets/scales');
 
 // Matches the audit default so lint and audit agree on what a spacing token is.
@@ -47,10 +53,40 @@ function readDirectDependencies(dir) {
  * installs are found by walking up; a stray global node_modules is never
  * consulted because the walk stops at the repository.
  */
-function projectRoots(cwd) {
+/**
+ * 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);
   for (;;) {
+    consult(path.join(current, 'package.json'));
     const direct = readDirectDependencies(current);
     if (direct) {
       roots.push({ dir: current, direct });
@@ -65,8 +101,12 @@ function projectRoots(cwd) {
 }
 
 function discoverTokenPackages(cwd = process.cwd()) {
+  return cachedByFiles(`packages:${path.resolve(cwd)}`, (consult) => discoverTokenPackagesUncached(cwd, consult));
+}
+
+function discoverTokenPackagesUncached(cwd, consult) {
   const sources = [];
-  const roots = projectRoots(cwd);
+  const roots = projectRoots(cwd, consult);
   for (const entry of TOKEN_PACKAGES) {
     // Only packages the project depends on directly count. A transitive
     // tailwindcss (for example via stylelint-config-tailwindcss) must not hand
@@ -75,14 +115,17 @@ function discoverTokenPackages(cwd = process.cwd()) {
     if (!owner) {
       continue;
     }
-    const root = roots
-      .map((candidate) => path.join(candidate.dir, 'node_modules', entry.name))
-      .find((dir) => fs.existsSync(path.join(dir, 'package.json')));
+    const candidates = roots.map((candidate) => path.join(candidate.dir, 'node_modules', entry.name));
+    for (const dir of candidates) {
+      consult(path.join(dir, 'package.json'));
+    }
+    const root = candidates.find((dir) => fs.existsSync(path.join(dir, 'package.json')));
     if (!root) {
       continue;
     }
     for (const file of entry.files) {
       const resolved = path.join(root, file);
+      consult(resolved);
       if (fs.existsSync(resolved)) {
         sources.push({
           format: 'auto',
@@ -176,8 +219,38 @@ function scaleFromSources(sources, baseFontSize) {
   return outcome;
 }
 
-/** Build a px scale from token definitions as produced by token-sources.js / contract.js. */
+/**
+ * Build a px scale from token definitions. Root-level declarations win: when
+ * the definitions declared in `:root`, `html` or `@theme` form a scale on
+ * their own, component-local variables (`--chip-spacing: 3px` inside `.chip`)
+ * are left out, because they are a component's parameters, not the project's
+ * scale (issue #54). When the root does not carry a scale, everything counts
+ * and the plausibility check is the backstop. Returns the values and the
+ * definitions that produced them, so provenance can name only those files.
+ */
+function inferScaleFromDefinitions(definitions, baseFontSize = 16) {
+  const rootOnly = new Map();
+  for (const [token, definition] of definitions) {
+    if (!definition.scopes || definition.scopes.has('root')) {
+      rootOnly.set(token, definition);
+    }
+  }
+  if (rootOnly.size > 0 && rootOnly.size < definitions.size) {
+    const fromRoot = scaleFromAllDefinitions(rootOnly, baseFontSize);
+    if (fromRoot) {
+      return { definitions: rootOnly, values: fromRoot };
+    }
+  }
+  const values = scaleFromAllDefinitions(definitions, baseFontSize);
+  return values ? { definitions, values } : null;
+}
+
 function scaleFromDefinitions(definitions, baseFontSize = 16) {
+  const inferred = inferScaleFromDefinitions(definitions, baseFontSize);
+  return inferred ? inferred.values : null;
+}
+
+function scaleFromAllDefinitions(definitions, baseFontSize) {
   const keys = [];
   const baseKeys = [];
   for (const definition of definitions.values()) {
@@ -191,6 +264,44 @@ function scaleFromDefinitions(definitions, baseFontSize = 16) {
   return scale.length >= MIN_INFERRED_SCALE_LENGTH ? scale : null;
 }
 
+/** The scope of a declaration node: the AST-side twin of customPropertyDeclarations. */
+function scopeOfNode(decl) {
+  for (let node = decl.parent; node; node = node.parent) {
+    if (node.type === 'rule') {
+      return String(node.selector).split(',').every((selector) => ROOT_SELECTOR.test(selector.trim())) ? 'root' : 'component';
+    }
+    if (node.type === 'atrule') {
+      const name = String(node.name).toLowerCase();
+      if (name === 'theme') return 'root';
+      if (!TRANSPARENT_AT_RULES.has(name)) return 'component';
+    }
+  }
+  return 'root';
+}
+
+const ROOT_SELECTOR = /^(?::root|html|:host|:(?:where|is)\(\s*(?::root|html)\s*\))$/i;
+const TRANSPARENT_AT_RULES = new Set(['media', 'supports', 'layer', 'container', 'scope', 'document']);
+
+/** Token definitions declared in the linted stylesheet itself: custom properties with their scope, plus Sass variables and maps. */
+function stylesheetDefinitions(root, tokenRegex, baseFontSize) {
+  const definitions = new Map();
+  root.walkDecls((decl) => {
+    const prop = decl.prop.toLowerCase();
+    if (!prop.startsWith('--') || !tokenRegex.test(prop)) {
+      return;
+    }
+    const parsed = parseTokenValueLength(decl.value);
+    if (!parsed || parsed.number === 0) {
+      return;
+    }
+    addDefinition(definitions, { baseFontSize, file: 'stylesheet', scope: scopeOfNode(decl), source: 'stylesheet', token: decl.prop, value: decl.value });
+  });
+  for (const sassToken of sassTokensFromRoot(root)) {
+    addDefinition(definitions, { baseFontSize, file: 'stylesheet', scope: 'root', source: 'stylesheet', token: sassToken.token, value: sassToken.value });
+  }
+  return definitions;
+}
+
 /**
  * Merge Tailwind-style base multiples into a scale when a bare --spacing/--space
  * base is defined. Only the first base found is expanded: a project that ships
@@ -225,6 +336,13 @@ function firstPositivePx(keys, baseFontSize) {
 
 function rcTokenSources(cwd) {
   const rcPath = path.join(cwd, RC_FILE);
+  return cachedByFiles(`rc:${rcPath}`, (consult) => {
+    consult(rcPath);
+    return rcTokenSourcesUncached(rcPath);
+  });
+}
+
+function rcTokenSourcesUncached(rcPath) {
   if (!fs.existsSync(rcPath)) {
     return [];
   }
@@ -251,7 +369,7 @@ function rcTokenSources(cwd) {
  * same collector the audit uses; component variables such as $dropdown-spacer
  * are excluded by the anchored name rule.
  */
-function sassValuesFromRoot(root) {
+function sassTokensFromRoot(root) {
   const lines = [];
   root.walkDecls((decl) => {
     if (typeof decl.prop === 'string' && decl.prop.startsWith('$')) {
@@ -261,7 +379,7 @@ function sassValuesFromRoot(root) {
   if (lines.length === 0) {
     return [];
   }
-  return collectScssTokens(lines.join('\n'), createTokenKindMatcher('spacing')).map((token) => token.value);
+  return collectScssTokens(lines.join('\n'), createTokenKindMatcher('spacing'));
 }
 
 function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
@@ -309,12 +427,7 @@ function resolveAutoScale({
 
   let rejected = null;
   if (root) {
-    const stylesheetMap = buildEffectiveTokenMap({
-      options: { baseFontSize, tokenMap: {}, tokenMapFromCssCustomProperties: true },
-      root,
-      tokenRegex,
-    });
-    const scale = scaleFromTokenMap(stylesheetMap, baseFontSize, sassValuesFromRoot(root));
+    const scale = scaleFromDefinitions(stylesheetDefinitions(root, tokenRegex, baseFontSize), baseFontSize);
     if (scale) {
       const assessment = assessScale({ source: 'stylesheet', values: scale });
       if (assessment.plausible) {
@@ -403,6 +516,27 @@ function fallbackInference(rejected = null) {
   };
 }
 
+/**
+ * Apply `scale: "auto"` to built rule options: the inferred scale replaces the
+ * placeholder and the inference is kept for the fallback note. Options with
+ * an explicit scale pass through untouched.
+ */
+function withResolvedScale(options, root) {
+  if (!options.scaleAuto) {
+    return options;
+  }
+  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;
+  return options;
+}
+
 function autoScaleFallbackNote(inference) {
   if (!inference || inference.source !== 'fallback') {
     return '';
@@ -419,6 +553,8 @@ module.exports = {
   assessScale,
   autoScaleFallbackNote,
   discoverTokenPackages,
+  inferScaleFromDefinitions,
   resolveAutoScale,
   scaleFromDefinitions,
+  withResolvedScale,
 };