stylelint-plugin-rhythmguard 1.8.0 → 2.0.0

package/src/cli/doctor.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { normalizeTokenSourceFormat } = require('../utils/token-sources');
 
 const cwd = process.cwd();
 let issues = 0;
@@ -205,6 +206,99 @@ function checkCustomSyntax(configContent) {
   }
 }
 
+function checkRhythmguardConfig() {
+  const configPath = path.join(cwd, '.rhythmguardrc.json');
+  if (!fs.existsSync(configPath)) {
+    skip('rhythmguard config check skipped (.rhythmguardrc.json not found)');
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    fail('.rhythmguardrc.json is not valid JSON', 'Fix or remove .rhythmguardrc.json');
+    return;
+  }
+
+  const audit = parsed.audit;
+  if (!audit || typeof audit !== 'object' || Array.isArray(audit)) {
+    fail('.rhythmguardrc.json audit config missing', 'Add an "audit" object or remove the config file');
+    return;
+  }
+
+  pass('.rhythmguardrc.json audit config valid');
+  checkRhythmguardTokenSources(audit, path.dirname(configPath));
+  checkRhythmguardMotionConfig(audit);
+  checkRhythmguardBaseline(audit);
+}
+
+function checkRhythmguardTokenSources(audit, baseDir) {
+  if (audit.tokenSources === undefined) {
+    skip('token source config check skipped (not configured)');
+    return;
+  }
+
+  if (!Array.isArray(audit.tokenSources)) {
+    fail('audit.tokenSources must be an array', 'Use strings or { "path": "...", "format": "..." } entries');
+    return;
+  }
+
+  for (const source of audit.tokenSources) {
+    const sourcePath = typeof source === 'string' ? source : source && source.path;
+    const format = typeof source === 'string' ? 'auto' : source && source.format;
+
+    if (typeof sourcePath !== 'string' || sourcePath.trim().length === 0) {
+      fail('token source entry missing path', 'Use strings or objects with a non-empty path');
+      continue;
+    }
+
+    try {
+      normalizeTokenSourceFormat(format || 'auto');
+    } catch {
+      fail(`token source format invalid for ${sourcePath}`, 'Use auto, css, flat-json, style-dictionary, or dtcg');
+    }
+
+    if (fs.existsSync(path.resolve(baseDir, sourcePath))) {
+      pass(`token source found (${sourcePath})`);
+    } else {
+      fail(`token source not found (${sourcePath})`, 'Update audit.tokenSources or create the token file');
+    }
+  }
+}
+
+function checkRhythmguardMotionConfig(audit) {
+  if (audit.includeMotion === undefined) {
+    skip('motion audit check skipped (not configured)');
+    return;
+  }
+
+  if (typeof audit.includeMotion === 'boolean') {
+    pass(`motion audit config valid (${audit.includeMotion})`);
+  } else {
+    fail('audit.includeMotion must be a boolean', 'Use true or false');
+  }
+}
+
+function checkRhythmguardBaseline(audit) {
+  const baselinePath = path.resolve(cwd, audit.baseline || '.rhythmguard-baseline.json');
+  if (!fs.existsSync(baselinePath)) {
+    skip('baseline freshness check skipped (baseline not found)');
+    return;
+  }
+
+  try {
+    const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    if (!Array.isArray(baseline.findings)) {
+      fail('baseline file does not include findings array', 'Regenerate it with rhythmguard audit --write-baseline');
+      return;
+    }
+    pass(`baseline file readable (${path.relative(cwd, baselinePath)})`);
+  } catch {
+    fail('baseline file is not valid JSON', 'Regenerate it with rhythmguard audit --write-baseline');
+  }
+}
+
 function run() {
   process.stdout.write('\nRhythmguard Doctor\n\n');
 
@@ -214,6 +308,7 @@ function run() {
   checkTokenPattern(configContent);
   checkTailwindConfig(configContent);
   checkCustomSyntax(configContent);
+  checkRhythmguardConfig();
 
   process.stdout.write('\n');
 

package/src/cli/index.js

@@ -27,7 +27,7 @@ if (!command || command === '--help' || command === '-h') {
 }
 
 if (command === 'audit') {
-  require('./audit');
+  require('./audit').run();
 } else if (command === 'init') {
   require('./init');
 } else if (command === 'doctor') {

package/src/configs/motion.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-motion-scale': [
+      true,
+      {
+        durationScale: [0, 75, 100, 150, 200, 300, 500, 700, 1000],
+      },
+    ],
+  },
+};

package/src/configs/motion.mjs

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const config = require('./motion.js');
+export default config;

package/src/eslint/index.js

@@ -1,15 +1,18 @@
 'use strict';
 
 const tailwindClassUseScale = require('./rules/tailwind-class-use-scale');
+const tailwindClassUseMotionScale = require('./rules/tailwind-class-use-motion-scale');
 
 module.exports = {
   rules: {
     'tailwind-class-use-scale': tailwindClassUseScale,
+    'tailwind-class-use-motion-scale': tailwindClassUseMotionScale,
   },
   configs: {
     recommended: {
       rules: {
         'rhythmguard-tailwind/tailwind-class-use-scale': 'warn',
+        'rhythmguard-tailwind/tailwind-class-use-motion-scale': 'off',
       },
     },
   },

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

@@ -0,0 +1,116 @@
+'use strict';
+
+const { formatTime } = require('../../utils/time');
+const { createTailwindMotionAnalyzer } = require('../../utils/tailwind-motion-analysis');
+
+const RULE_NAME = 'tailwind-class-use-motion-scale';
+
+function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
+  const rawText = sourceCode.getText(node);
+  let value = null;
+  let quote = null;
+
+  if (node.type === 'Literal' && typeof node.value === 'string') {
+    value = node.value;
+    quote = rawText[0] === '"' || rawText[0] === "'" ? rawText[0] : '"';
+  }
+
+  if (node.type === 'TemplateElement') {
+    value = node.value.raw;
+  }
+
+  if (!value || typeof value !== 'string') {
+    return;
+  }
+
+  const findings = analyzer.analyzeClassString(value);
+  if (findings.length === 0) {
+    return;
+  }
+
+  let fixedValue = value;
+  let fixedValueOffset = 0;
+
+  for (const { analysis, segment } of findings) {
+    if (allowFix && analysis.reason === 'duration' && node.type === 'Literal') {
+      const replacementStart = segment.start + fixedValueOffset;
+      fixedValue = `${fixedValue.slice(0, replacementStart)}${analysis.fixedToken}${fixedValue.slice(replacementStart + segment.token.length)}`;
+      fixedValueOffset += analysis.fixedToken.length - segment.token.length;
+    }
+  }
+
+  const fixedText = allowFix && node.type === 'Literal' && fixedValue !== value
+    ? `${quote}${fixedValue.replace(new RegExp(quote, 'g'), `\\${quote}`)}${quote}`
+    : null;
+
+  for (const { analysis, segment } of findings) {
+    const lower = analysis.nearest
+      ? formatTime(analysis.nearest.lower, 'ms')
+      : 'n/a';
+    const upper = analysis.nearest
+      ? formatTime(analysis.nearest.upper, 'ms')
+      : 'n/a';
+    context.report({
+      message: buildMessage(analysis, segment, lower, upper),
+      node,
+      fix:
+        fixedText && analysis.reason === 'duration'
+          ? (fixer) => fixer.replaceText(node, fixedText)
+          : null,
+    });
+  }
+}
+
+function buildMessage(analysis, segment, lower, upper) {
+  if (analysis.reason === 'easing') {
+    return `Unexpected Tailwind arbitrary motion easing "${segment.token}". Use motion tokens for easing decisions.`;
+  }
+
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use non-negative duration values.`;
+  }
+
+  return `Unexpected Tailwind arbitrary motion duration "${segment.token}". Use duration scale values (nearest: ${lower} or ${upper}).`;
+}
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Enforce duration scale for Tailwind arbitrary motion utilities in class strings',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          durationScale: {
+            items: { type: 'number' },
+            type: 'array',
+          },
+          durationUnits: {
+            items: {
+              enum: ['ms', 's'],
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+  },
+  create(context) {
+    const analyzer = createTailwindMotionAnalyzer(context.options && context.options[0]);
+    const sourceCode = context.sourceCode || context.getSourceCode();
+
+    return {
+      Literal(node) {
+        maybeCheckNodeText(node, sourceCode, context, analyzer, true);
+      },
+      TemplateElement(node) {
+        maybeCheckNodeText(node, sourceCode, context, analyzer, false);
+      },
+    };
+  },
+  ruleName: RULE_NAME,
+};

package/src/index.js

@@ -3,14 +3,16 @@
 const useScale = require('./rules/use-scale');
 const preferToken = require('./rules/prefer-token');
 const noOffscaleTransform = require('./rules/no-offscale-transform');
+const useMotionScale = require('./rules/use-motion-scale');
 
-const rules = [useScale, preferToken, noOffscaleTransform];
+const rules = [useScale, preferToken, noOffscaleTransform, useMotionScale];
 
 module.exports = rules;
 module.exports.rules = {
   [useScale.ruleName]: useScale,
   [preferToken.ruleName]: preferToken,
   [noOffscaleTransform.ruleName]: noOffscaleTransform,
+  [useMotionScale.ruleName]: useMotionScale,
 };
 module.exports.configs = {
   recommended: require('./configs/recommended'),
@@ -19,6 +21,8 @@ module.exports.configs = {
   expanded: require('./configs/expanded'),
   logical: require('./configs/logical'),
   migration: require('./configs/migration'),
+  motion: require('./configs/motion'),
 };
 module.exports.eslint = require('./eslint');
 module.exports.presets = require('./presets');
+module.exports.audit = require('./audit');

package/src/index.mjs

@@ -8,3 +8,4 @@ export const rules = plugin.rules;
 export const configs = plugin.configs;
 export const presets = plugin.presets;
 export const eslint = plugin.eslint;
+export const audit = plugin.audit;

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

@@ -0,0 +1,245 @@
+'use strict';
+
+const stylelint = require('stylelint');
+const valueParser = require('postcss-value-parser');
+const {
+  nearestScaleValues,
+  numbersEqual,
+} = require('../../utils/length');
+const {
+  declarationValueIndex,
+  walkRootValueNodes,
+} = require('../../utils/value-utils');
+const {
+  formatTime,
+  fromMs,
+  normalizeDurationScale,
+  normalizeDurationUnits,
+  parseTimeToken,
+  toMs,
+} = require('../../utils/time');
+
+const ruleName = 'rhythmguard/use-motion-scale';
+const DURATION_PROPERTIES = new Set([
+  'transition-duration',
+  'transition-delay',
+  'animation-duration',
+  'animation-delay',
+  'transition',
+  'animation',
+]);
+const EASING_PROPERTIES = new Set([
+  'transition-timing-function',
+  'animation-timing-function',
+  'transition',
+  'animation',
+]);
+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.`,
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function buildOptions(rawOptions) {
+  const options = rawOptions || {};
+
+  return {
+    durationScale: normalizeDurationScale(options.durationScale),
+    durationUnits: normalizeDurationUnits(options.durationUnits),
+    easingTokenMap: isPlainObject(options.easingTokenMap) ? options.easingTokenMap : {},
+    fixToScale: options.fixToScale !== false,
+  };
+}
+
+function validateSecondaryOptions(result, secondaryOptions) {
+  return stylelint.utils.validateOptions(result, ruleName, {
+    actual: secondaryOptions,
+    optional: true,
+    possible: {
+      durationScale: [(value) =>
+        typeof value === 'number' &&
+        Number.isFinite(value) &&
+        value >= 0],
+      durationUnits: [(value) => value === 'ms' || value === 's'],
+      easingTokenMap: [(value) =>
+        isPlainObject(value) &&
+        Object.values(value).every((entry) =>
+          typeof entry === 'string' && entry.trim().length > 0,
+        )],
+      fixToScale: [true, false],
+    },
+  });
+}
+
+function getFixedNodeValue(parsedTime, nearestMs, options) {
+  if (!options.durationUnits.includes(parsedTime.unit)) {
+    return null;
+  }
+
+  const converted = fromMs(nearestMs, parsedTime.unit);
+  if (converted === null) {
+    return null;
+  }
+
+  return formatTime(converted, parsedTime.unit);
+}
+
+function functionToString(node) {
+  return valueParser.stringify(node);
+}
+
+const ruleFunction = (primary, secondaryOptions) => {
+  return (root, result) => {
+    const valid = stylelint.utils.validateOptions(result, ruleName, {
+      actual: primary,
+      possible: [true],
+    });
+
+    if (!valid || !validateSecondaryOptions(result, secondaryOptions)) {
+      return;
+    }
+
+    const options = buildOptions(secondaryOptions);
+
+    root.walkDecls((decl) => {
+      const prop = decl.prop.toLowerCase();
+      if (!DURATION_PROPERTIES.has(prop) && !EASING_PROPERTIES.has(prop)) {
+        return;
+      }
+
+      const parsed = valueParser(decl.value);
+      let changed = false;
+
+      const reportDuration = (node, nearest, fixedValue = null) => {
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const payload = {
+          endIndex: index + node.value.length,
+          index,
+          message: nearest
+            ? messages.rejectedDuration(
+              node.value,
+              formatTime(nearest.lower, 'ms'),
+              formatTime(nearest.upper, 'ms'),
+            )
+            : messages.invalidDuration(node.value),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (fixedValue) {
+          payload.fix = () => {
+            node.value = fixedValue;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      const reportEasing = (node, replacement = null) => {
+        const source = functionToString(node);
+        const index = declarationValueIndex(decl) + node.sourceIndex;
+        const payload = {
+          endIndex: index + source.length,
+          index,
+          message: messages.rejectedEasing(source),
+          node: decl,
+          result,
+          ruleName,
+        };
+
+        if (replacement) {
+          payload.fix = () => {
+            node.type = 'word';
+            node.value = replacement;
+            delete node.nodes;
+            return true;
+          };
+        }
+
+        stylelint.utils.report(payload);
+      };
+
+      walkRootValueNodes(parsed, (node) => {
+        if (node.type === 'function') {
+          const functionName = node.value.toLowerCase();
+          if (!EASING_PROPERTIES.has(prop) || !EASING_FUNCTIONS.has(functionName)) {
+            return false;
+          }
+
+          const source = functionToString(node);
+          reportEasing(node, options.easingTokenMap[source] || null);
+          changed = changed || Boolean(options.easingTokenMap[source]);
+          return true;
+        }
+
+        if (node.type !== 'word' || !DURATION_PROPERTIES.has(prop)) {
+          return false;
+        }
+
+        const parsedTime = parseTimeToken(node.value);
+        if (!parsedTime) {
+          return false;
+        }
+
+        if (parsedTime.number < 0) {
+          reportDuration(node, null);
+          return false;
+        }
+
+        if (!options.durationUnits.includes(parsedTime.unit)) {
+          return false;
+        }
+
+        const msValue = toMs(parsedTime.number, parsedTime.unit);
+        if (msValue === null) {
+          return false;
+        }
+
+        const isOnScale = options.durationScale.some((scaleValue) => numbersEqual(scaleValue, msValue));
+        if (isOnScale) {
+          return false;
+        }
+
+        const nearest = nearestScaleValues(msValue, options.durationScale);
+        if (!nearest) {
+          return false;
+        }
+
+        const fixedValue = options.fixToScale
+          ? getFixedNodeValue(parsedTime, nearest.nearest, options)
+          : null;
+
+        reportDuration(node, nearest, fixedValue);
+        changed = changed || Boolean(fixedValue);
+        return false;
+      });
+
+      if (changed) {
+        decl.value = parsed.toString();
+      }
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+ruleFunction.meta = {
+  fixable: true,
+  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-motion-scale',
+};
+
+module.exports = stylelint.createPlugin(ruleName, ruleFunction);
+module.exports.ruleName = ruleName;
+module.exports.messages = messages;
+module.exports.meta = ruleFunction.meta;

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

@@ -0,0 +1,7 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const rule = require('./index.js');
+export default rule;
+export const ruleName = rule.ruleName;
+export const messages = rule.messages;
+export const meta = rule.meta;

package/src/utils/constants.js

@@ -35,6 +35,10 @@ const PROPERTY_GROUP_PATTERNS = Object.freeze({
     /^letter-spacing$/,
     /^word-spacing$/,
   ]),
+  motion: Object.freeze([
+    /^transition(?:-.+)?$/,
+    /^animation(?:-.+)?$/,
+  ]),
 });
 
 const DEFAULT_PROPERTY_GROUPS = Object.freeze(['spacing']);