stylelint-plugin-rhythmguard 3.2.0 → 3.4.0

package/src/audit/scan/stylesheets.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * Findings from stylesheets: run the rules through Stylelint's API, turn each
+ * warning into a finding, and recover the CSS property at the warning position
+ * from the source, since Stylelint reports positions rather than nodes.
+ */
+const fs = require('node:fs');
+const {
+  DEFAULT_AUDIT_TOKEN_PATTERN,
+  formatPath,
+  pluginPath,
+} = require('../shared');
+const { isScssFile } = require('./files');
+
+let scssSyntaxCache;
+
+/**
+ * postcss-scss is an optional peer. Resolve it from the audited project first,
+ * then from this package. Returns null when unavailable; SCSS files are then
+ * counted as skipped instead of failing the audit.
+ */
+function resolveScssSyntax() {
+  if (scssSyntaxCache !== undefined) {
+    return scssSyntaxCache;
+  }
+  try {
+    scssSyntaxCache = require.resolve('postcss-scss', { paths: [process.cwd(), __dirname] });
+  } catch {
+    scssSyntaxCache = null;
+  }
+  return scssSyntaxCache;
+}
+
+async function runStylelintAudit(cssFiles, options) {
+  if (cssFiles.length === 0) {
+    const empty = [];
+    empty.scssFiles = 0;
+    empty.scssSkipped = 0;
+    return empty;
+  }
+
+  const { default: stylelint } = await import('stylelint');
+  const rules = {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+      },
+    ],
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+        tokenMapFromCssCustomProperties: true,
+        tokenPattern: DEFAULT_AUDIT_TOKEN_PATTERN,
+      },
+    ],
+  };
+
+  if (options.includeMotion) {
+    rules['rhythmguard/use-motion-scale'] = [
+      true,
+      {
+        severity: 'warning',
+      },
+    ];
+  }
+
+  const plainFiles = cssFiles.filter((file) => !isScssFile(file));
+  const scssFiles = cssFiles.filter(isScssFile);
+  const results = [];
+
+  if (plainFiles.length > 0) {
+    const result = await stylelint.lint({
+      files: plainFiles,
+      config: {
+        plugins: [pluginPath],
+        rules,
+      },
+    });
+    results.push(...(result.results || []));
+  }
+
+  let scssSkipped = 0;
+  if (scssFiles.length > 0) {
+    const scssSyntax = resolveScssSyntax();
+    if (scssSyntax) {
+      const result = await stylelint.lint({
+        files: scssFiles,
+        config: {
+          customSyntax: scssSyntax,
+          plugins: [pluginPath],
+          rules,
+        },
+      });
+      results.push(...(result.results || []));
+    } else {
+      scssSkipped = scssFiles.length;
+    }
+  }
+
+  results.scssFiles = scssFiles.length;
+  results.scssSkipped = scssSkipped;
+  return results;
+}
+
+function collectCssFindings(fileResults) {
+  const findings = [];
+  const sources = new Map();
+
+  for (const fileResult of fileResults) {
+    for (const warning of fileResult.warnings || []) {
+      const text = warning.text || '';
+      const source = readSourceOnce(sources, fileResult.source);
+      const offScaleMatch = text.match(
+        /Unexpected (?:off-scale value|transform translation value) "([^"]+)"/,
+      );
+      const tokenMatch = text.match(
+        /Unexpected raw scale value "([^"]+)"/,
+      );
+      const motionDurationMatch = text.match(
+        /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,
+      );
+      const motionEasingMatch = text.match(
+        /Unexpected raw motion easing "([^"]+)"/,
+      );
+
+      findings.push({
+        column: warning.column || 1,
+        file: formatPath(fileResult.source),
+        line: warning.line || 1,
+        property: source === null
+          ? null
+          : findDeclarationProperty(source, warning.line || 1, warning.column || 1),
+        rule: warning.rule || 'rhythmguard',
+        text,
+        type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
+        value: getCssFindingValue({
+          motionDurationMatch,
+          motionEasingMatch,
+          offScaleMatch,
+          tokenMatch,
+        }),
+      });
+    }
+  }
+
+  return findings;
+}
+
+function readSourceOnce(cache, filePath) {
+  if (!filePath) {
+    return null;
+  }
+  if (!cache.has(filePath)) {
+    try {
+      cache.set(filePath, fs.readFileSync(filePath, 'utf8'));
+    } catch {
+      cache.set(filePath, null);
+    }
+  }
+  return cache.get(filePath);
+}
+
+const DECLARATION_BOUNDARY = new Set([';', '{', '}']);
+
+const DECLARATION_HEAD_PATTERN = /^\s*(?:(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*)\s*)*(--[\w-]+|[a-zA-Z][\w-]*)\s*:/;
+
+/**
+ * Stylelint warnings carry a position but not the declaration node. Recover the
+ * property by walking from the warning position back to the previous declaration
+ * boundary and reading the `property:` head, skipping block and Sass line comments.
+ * Sass interpolation is blanked first so `#{...}` braces do not act as boundaries. Returns null when the position is not
+ * inside a declaration, for example inside an at-rule.
+ */
+
+function findDeclarationProperty(source, line, column) {
+  const offset = positionToOffset(source, line, column);
+  if (offset === null) {
+    return null;
+  }
+
+  const text = source.replace(/#\{[^}]*\}/g, (match) => ' '.repeat(match.length));
+  let start = offset;
+  while (start > 0 && !DECLARATION_BOUNDARY.has(text[start - 1])) {
+    start -= 1;
+  }
+  const backward = text.slice(start, offset).match(DECLARATION_HEAD_PATTERN);
+  if (backward) {
+    return backward[1];
+  }
+
+  let end = offset;
+  while (end < text.length && !DECLARATION_BOUNDARY.has(text[end])) {
+    end += 1;
+  }
+  const forward = text.slice(offset, end).match(DECLARATION_HEAD_PATTERN);
+  return forward ? forward[1] : null;
+}
+
+function positionToOffset(source, line, column) {
+  if (!Number.isInteger(line) || line < 1) {
+    return null;
+  }
+  let offset = 0;
+  let currentLine = 1;
+  while (currentLine < line) {
+    const newline = source.indexOf('\n', offset);
+    if (newline === -1) {
+      return null;
+    }
+    offset = newline + 1;
+    currentLine += 1;
+  }
+  const lineEnd = source.indexOf('\n', offset);
+  const lineLength = (lineEnd === -1 ? source.length : lineEnd) - offset;
+  return offset + Math.min(Math.max((column || 1) - 1, 0), lineLength);
+}
+
+function getCssFindingValue({
+  motionDurationMatch,
+  motionEasingMatch,
+  offScaleMatch,
+  tokenMatch,
+}) {
+  if (tokenMatch) {
+    return tokenMatch[1];
+  }
+
+  if (offScaleMatch) {
+    return offScaleMatch[1];
+  }
+
+  if (motionDurationMatch) {
+    return motionDurationMatch[1];
+  }
+
+  if (motionEasingMatch) {
+    return motionEasingMatch[1];
+  }
+
+  return null;
+}
+
+function getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }) {
+  if (motionDurationMatch) {
+    return 'motion-duration';
+  }
+
+  if (motionEasingMatch) {
+    return 'motion-easing';
+  }
+
+  if (tokenMatch) {
+    return 'token-opportunity';
+  }
+
+  return 'off-scale';
+}
+
+module.exports = {
+  collectCssFindings,
+  findDeclarationProperty,
+  getCssFindingType,
+  getCssFindingValue,
+  positionToOffset,
+  readSourceOnce,
+  resolveScssSyntax,
+  runStylelintAudit,
+};

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')];
@@ -160,7 +160,10 @@ async function run() {
   out.push('  Scale');
   out.push(`    Scale           ${scale.values.join(', ')}`);
   out.push(`    Source          ${describeScale(scale)}`);
-  if (scale.source === 'fallback') {
+  if (scale.source === 'fallback' && scale.rejected) {
+    out.push(`    Note            Spacing tokens were found but do not form a scale (${scale.rejected.reasons.join(', ')}); the rhythmic-4 preset is being used.`);
+    out.push('                    Point scaleSources at your real token file, or tighten tokenPattern.');
+  } else if (scale.source === 'fallback') {
     out.push('    Note            No spacing tokens found; the rhythmic-4 preset is being used.');
     out.push('                    Add scaleSources or define --space-*/--spacing-* custom properties to lint against your own scale.');
   }

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

@@ -69,8 +69,10 @@ function formatNumber(value) {
     return '0';
   }
 
+  // String() already prints the shortest form (1.5, not 1.50). The old
+  // trailing-zero strip also turned 30 into 3 and 100 into 1.
   const rounded = Math.round(value * 10000) / 10000;
-  return String(rounded).replace(/\.?0+$/, '');
+  return String(rounded);
 }
 
 function formatLength(number, unit) {
@@ -180,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,
 };