stylelint-plugin-rhythmguard 1.4.2 → 1.6.0

package/src/cli/doctor.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const cwd = process.cwd();
+let issues = 0;
+
+function pass(msg) {
+  process.stdout.write(`✓ ${msg}\n`);
+}
+
+function fail(msg, fix) {
+  issues++;
+  process.stdout.write(`✗ ${msg}\n`);
+  if (fix) {
+    process.stdout.write(`  → ${fix}\n`);
+  }
+}
+
+function skip(msg) {
+  process.stdout.write(`- ${msg}\n`);
+}
+
+// Check 1: Stylelint installed
+function checkStylelint() {
+  try {
+    const stylelintPkg = require.resolve('stylelint/package.json', {
+      paths: [cwd],
+    });
+    const version = require(stylelintPkg).version;
+    pass(`stylelint installed (v${version})`);
+    return true;
+  } catch {
+    fail(
+      'stylelint not installed',
+      'Run: npm install --save-dev stylelint',
+    );
+    return false;
+  }
+}
+
+// Check 2: Config found
+function findConfig() {
+  const configFiles = [
+    '.stylelintrc',
+    '.stylelintrc.json',
+    '.stylelintrc.js',
+    '.stylelintrc.cjs',
+    '.stylelintrc.mjs',
+    '.stylelintrc.yml',
+    '.stylelintrc.yaml',
+    'stylelint.config.js',
+    'stylelint.config.cjs',
+    'stylelint.config.mjs',
+  ];
+
+  for (const file of configFiles) {
+    const fullPath = path.join(cwd, file);
+    if (fs.existsSync(fullPath)) {
+      pass(`config found (${file})`);
+      return fullPath;
+    }
+  }
+
+  // Check package.json
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.stylelint) {
+        pass('config found (package.json stylelint key)');
+        return pkgPath;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  fail(
+    'no Stylelint config found',
+    'Run: npx rhythmguard init',
+  );
+  return null;
+}
+
+// Check 3: Config references Rhythmguard
+function checkConfigReferences(configPath) {
+  if (!configPath) {
+    skip('config reference check skipped (no config)');
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf8');
+
+    if (content.includes('rhythmguard')) {
+      pass('config references rhythmguard');
+      return content;
+    }
+
+    // Check package.json stylelint key
+    if (configPath.endsWith('package.json')) {
+      const pkg = JSON.parse(content);
+      const stylelintConfig = JSON.stringify(pkg.stylelint || {});
+      if (stylelintConfig.includes('rhythmguard')) {
+        pass('config references rhythmguard');
+        return stylelintConfig;
+      }
+    }
+
+    fail(
+      'config does not reference rhythmguard',
+      'Add: "extends": ["stylelint-plugin-rhythmguard/configs/recommended"]',
+    );
+    return content;
+  } catch {
+    fail(
+      'could not read config file',
+      `Check permissions on ${configPath}`,
+    );
+    return null;
+  }
+}
+
+// Check 4: Token pattern valid
+function checkTokenPattern(configContent) {
+  if (!configContent) {
+    skip('token pattern check skipped (no config content)');
+    return;
+  }
+
+  const patternMatch = configContent.match(
+    /tokenPattern['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!patternMatch) {
+    skip('token pattern check skipped (not configured)');
+    return;
+  }
+
+  try {
+    new RegExp(patternMatch[1]);
+    pass(`token pattern valid (${patternMatch[1]})`);
+  } catch {
+    fail(
+      `token pattern invalid: ${patternMatch[1]}`,
+      'Fix the regex in tokenPattern option',
+    );
+  }
+}
+
+// Check 5: Tailwind config exists
+function checkTailwindConfig(configContent) {
+  if (!configContent) {
+    skip('tailwind config check skipped (no config content)');
+    return;
+  }
+
+  const tailwindPathMatch = configContent.match(
+    /tailwindConfigPath['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!tailwindPathMatch) {
+    skip('tailwind config check skipped (not configured)');
+    return;
+  }
+
+  const tailwindPath = path.resolve(cwd, tailwindPathMatch[1]);
+  if (fs.existsSync(tailwindPath)) {
+    pass(`tailwind config found (${tailwindPathMatch[1]})`);
+  } else {
+    fail(
+      `tailwind config not found at ${tailwindPathMatch[1]}`,
+      'Update tailwindConfigPath or remove tokenMapFromTailwindSpacing',
+    );
+  }
+}
+
+// Check 6: Custom syntax installed
+function checkCustomSyntax(configContent) {
+  if (!configContent) {
+    skip('custom syntax check skipped (no config content)');
+    return;
+  }
+
+  const syntaxMatch = configContent.match(
+    /customSyntax['":\s]+['"]([^'"]+)['"]/,
+  );
+
+  if (!syntaxMatch) {
+    skip('custom syntax check skipped (not configured)');
+    return;
+  }
+
+  const pkg = syntaxMatch[1];
+  try {
+    require.resolve(pkg, { paths: [cwd] });
+    pass(`custom syntax installed (${pkg})`);
+  } catch {
+    fail(
+      `custom syntax package not installed: ${pkg}`,
+      `Run: npm install --save-dev ${pkg}`,
+    );
+  }
+}
+
+function run() {
+  process.stdout.write('\nRhythmguard Doctor\n\n');
+
+  const stylelintOk = checkStylelint();
+  const configPath = findConfig();
+  const configContent = checkConfigReferences(configPath);
+  checkTokenPattern(configContent);
+  checkTailwindConfig(configContent);
+  checkCustomSyntax(configContent);
+
+  process.stdout.write('\n');
+
+  if (issues === 0) {
+    process.stdout.write('All checks passed.\n\n');
+  } else {
+    process.stdout.write(
+      `${issues} issue${issues === 1 ? '' : 's'} found.\n\n`,
+    );
+  }
+
+  process.exit(stylelintOk && issues === 0 ? 0 : 1);
+}
+
+run();

package/src/cli/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+'use strict';
+
+const command = process.argv[2];
+
+const HELP = `Usage: rhythmguard <command>
+
+Commands:
+  audit <dir>   Report design-system drift across CSS and Tailwind class strings
+  init          Scaffold a Rhythmguard config for your project
+  doctor        Validate your Rhythmguard setup
+
+Options:
+  --help        Show this help message
+
+Examples:
+  npx rhythmguard audit ./src
+  npx rhythmguard audit ./src --json
+  npx rhythmguard audit ./src --format markdown
+  npx rhythmguard init
+  npx rhythmguard doctor
+`;
+
+if (!command || command === '--help' || command === '-h') {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+if (command === 'audit') {
+  require('./audit');
+} else if (command === 'init') {
+  require('./init');
+} else if (command === 'doctor') {
+  require('./doctor');
+} else {
+  process.stderr.write(`Unknown command: ${command}\n\n`);
+  process.stdout.write(HELP);
+  process.exit(1);
+}

package/src/cli/init.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const readline = require('node:readline');
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function detect() {
+  const cwd = process.cwd();
+  const pkgPath = path.join(cwd, 'package.json');
+
+  let pkg = {};
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {
+      // ignore
+    }
+  }
+
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  const hasTailwindConfig =
+    fs.existsSync(path.join(cwd, 'tailwind.config.js')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.cjs')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.mjs')) ||
+    fs.existsSync(path.join(cwd, 'tailwind.config.ts'));
+
+  const hasTailwindDep = Boolean(
+    allDeps.tailwindcss || allDeps['@tailwindcss/postcss'],
+  );
+
+  const hasNextConfig =
+    fs.existsSync(path.join(cwd, 'next.config.js')) ||
+    fs.existsSync(path.join(cwd, 'next.config.mjs')) ||
+    fs.existsSync(path.join(cwd, 'next.config.ts'));
+
+  const hasExistingConfig =
+    fs.existsSync(path.join(cwd, '.stylelintrc')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.json')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.js')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.cjs')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.mjs')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.yml')) ||
+    fs.existsSync(path.join(cwd, '.stylelintrc.yaml')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.js')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.cjs')) ||
+    fs.existsSync(path.join(cwd, 'stylelint.config.mjs')) ||
+    Boolean(pkg.stylelint);
+
+  const tailwind = hasTailwindConfig || hasTailwindDep;
+  const nextjs = hasNextConfig;
+
+  return { tailwind, nextjs, hasExistingConfig };
+}
+
+function selectProfile(stack) {
+  if (stack.nextjs && stack.tailwind) {
+    return 'react-tailwind';
+  }
+  if (stack.tailwind) {
+    return 'tailwind';
+  }
+  return 'recommended';
+}
+
+async function run() {
+  process.stdout.write('\nRhythmguard Init\n\n');
+
+  const stack = detect();
+
+  // Report detection
+  const detected = [];
+  if (stack.tailwind) detected.push('Tailwind CSS');
+  if (stack.nextjs) detected.push('Next.js');
+  if (detected.length > 0) {
+    process.stdout.write(`Detected: ${detected.join(', ')}\n`);
+  } else {
+    process.stdout.write('Detected: plain CSS project\n');
+  }
+
+  // Warn about existing config
+  if (stack.hasExistingConfig) {
+    process.stdout.write('\n⚠ Existing Stylelint config found.\n');
+    const answer = await ask('Overwrite? (y/n) ');
+    if (answer !== 'y' && answer !== 'yes') {
+      process.stdout.write('Aborted.\n');
+      process.exit(0);
+    }
+  }
+
+  const profile = selectProfile(stack);
+  process.stdout.write(`\nProfile: ${profile}\n`);
+
+  const answer = await ask('Write .stylelintrc.json? (y/n) ');
+  if (answer !== 'y' && answer !== 'yes') {
+    process.stdout.write('Aborted.\n');
+    process.exit(0);
+  }
+
+  const config = {
+    extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+  };
+
+  const configPath = path.join(process.cwd(), '.stylelintrc.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  process.stdout.write(`\n✓ Wrote ${configPath}\n`);
+  process.stdout.write(`\nNext steps:\n`);
+  process.stdout.write(`  npx stylelint "src/**/*.css"\n\n`);
+}
+
+run();

package/src/configs/react-tailwind.js

@@ -0,0 +1,25 @@
+'use strict';
+
+module.exports = {
+  extends: [
+    'stylelint-plugin-rhythmguard/configs/tailwind',
+  ],
+  ignoreFiles: [
+    '.next/**',
+    'out/**',
+    'node_modules/**',
+  ],
+  overrides: [
+    {
+      files: ['**/*.module.css'],
+      rules: {
+        'rhythmguard/use-scale': [
+          true,
+          {
+            propertyGroups: ['spacing', 'radius'],
+          },
+        ],
+      },
+    },
+  ],
+};

package/src/configs/react-tailwind.mjs

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

package/src/configs/tailwind.js

@@ -5,4 +5,13 @@ module.exports = {
     'stylelint-config-tailwindcss',
     'stylelint-plugin-rhythmguard/configs/strict',
   ],
+  rules: {
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        tokenPattern: '^--spacing-',
+        tokenMapFromCssCustomProperties: true,
+      },
+    ],
+  },
 };

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

@@ -1,112 +1,11 @@
 'use strict';
 
-const {
-  formatLength,
-  nearestScaleValues,
-  normalizeScale,
-  numbersEqual,
-  parseLengthToken,
-  toPx,
-} = require('../../utils/length');
+const { formatLength } = require('../../utils/length');
+const { createTailwindClassAnalyzer } = require('../../utils/tailwind-class-analysis');
 
 const RULE_NAME = 'tailwind-class-use-scale';
 
-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>[^\]]+)\]$/;
-
-function getOptions(context) {
-  const option = context.options && context.options[0] ? context.options[0] : {};
-
-  return {
-    allowNegative: option.allowNegative !== false,
-    baseFontSize:
-      typeof option.baseFontSize === 'number' &&
-      Number.isFinite(option.baseFontSize) &&
-      option.baseFontSize > 0
-        ? option.baseFontSize
-        : 16,
-    scale: Array.isArray(option.scale)
-      ? option.scale
-      : [0, 4, 8, 12, 16, 24, 32],
-    units: Array.isArray(option.units)
-      ? option.units.map((unit) => String(unit).toLowerCase())
-      : ['px', 'rem', 'em'],
-  };
-}
-
-function findClassSegments(value) {
-  const segments = [];
-  const tokenRegex = /\S+/g;
-  let match;
-
-  while ((match = tokenRegex.exec(value)) !== null) {
-    segments.push({
-      start: match.index,
-      token: match[0],
-    });
-  }
-
-  return segments;
-}
-
-function analyzeToken(token, options, scalePx) {
-  const match = token.match(ARBITRARY_SPACING_CLASS);
-  if (!match || !match.groups) {
-    return null;
-  }
-
-  const parsedLength = parseLengthToken(match.groups.rawValue);
-  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '') {
-    return null;
-  }
-
-  if (!options.allowNegative && parsedLength.number < 0) {
-    return {
-      nearest: null,
-      parsedLength,
-      reason: 'negative',
-    };
-  }
-
-  if (!options.units.includes(parsedLength.unit)) {
-    return null;
-  }
-
-  const pxValue = toPx(Math.abs(parsedLength.number), parsedLength.unit, options.baseFontSize);
-  if (pxValue === null) {
-    return null;
-  }
-
-  const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
-  if (isOnScale) {
-    return null;
-  }
-
-  const nearest = nearestScaleValues(pxValue, scalePx);
-  if (!nearest) {
-    return null;
-  }
-
-  const signedNearest = parsedLength.number < 0
-    ? -Math.abs(nearest.nearest)
-    : nearest.nearest;
-
-  const replacementValuePx = signedNearest;
-  const replacementNumber = parsedLength.unit === 'px'
-    ? replacementValuePx
-    : replacementValuePx / options.baseFontSize;
-
-  const replacementValue = formatLength(replacementNumber, parsedLength.unit);
-  const fixedToken = token.replace(match.groups.rawValue, replacementValue);
-
-  return {
-    fixedToken,
-    nearest,
-    parsedLength,
-    reason: 'off-scale',
-  };
-}
-
-function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFix) {
+function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
   const rawText = sourceCode.getText(node);
   let value = null;
   let quote = null;
@@ -124,16 +23,27 @@ function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFi
     return;
   }
 
-  const segments = findClassSegments(value);
-  if (segments.length === 0) {
+  const findings = analyzer.analyzeClassString(value);
+  if (findings.length === 0) {
     return;
   }
-  for (const segment of segments) {
-    const analysis = analyzeToken(segment.token, options, scalePx);
-    if (!analysis) {
-      continue;
+
+  let fixedValue = value;
+  let fixedValueOffset = 0;
+
+  for (const { analysis, segment } of findings) {
+    if (allowFix && analysis.reason !== 'negative' && 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
       ? formatLength(analysis.nearest.lower, 'px')
       : 'n/a';
@@ -147,12 +57,8 @@ function maybeCheckNodeText(node, sourceCode, context, options, scalePx, allowFi
           : `Unexpected Tailwind arbitrary spacing value "${segment.token}". Use scale values (nearest: ${lower} or ${upper}).`,
       node,
       fix:
-        allowFix && analysis.reason !== 'negative' && node.type === 'Literal'
-          ? (fixer) => {
-            const nextValue = `${value.slice(0, segment.start)}${analysis.fixedToken}${value.slice(segment.start + segment.token.length)}`;
-            const escaped = nextValue.replace(new RegExp(quote, 'g'), `\\${quote}`);
-            return fixer.replaceText(node, `${quote}${escaped}${quote}`);
-          }
+        fixedText && analysis.reason !== 'negative'
+          ? (fixer) => fixer.replaceText(node, fixedText)
           : null,
     });
   }
@@ -189,16 +95,15 @@ module.exports = {
     ],
   },
   create(context) {
-    const options = getOptions(context);
-    const scalePx = normalizeScale(options.scale, options.baseFontSize);
+    const analyzer = createTailwindClassAnalyzer(context.options && context.options[0]);
     const sourceCode = context.sourceCode || context.getSourceCode();
 
     return {
       Literal(node) {
-        maybeCheckNodeText(node, sourceCode, context, options, scalePx, true);
+        maybeCheckNodeText(node, sourceCode, context, analyzer, true);
       },
       TemplateElement(node) {
-        maybeCheckNodeText(node, sourceCode, context, options, scalePx, false);
+        maybeCheckNodeText(node, sourceCode, context, analyzer, false);
       },
     };
   },