stylelint-plugin-rhythmguard 2.0.1 → 2.2.0

package/src/cli/index.js

@@ -3,9 +3,13 @@
 
 const command = process.argv[2];
 
-const HELP = `Usage: rhythmguard <command>
+const HELP = `Usage: rhythmguard [command]
+
+With no command: zero-config quickstart. Detects your stack and tokens, infers
+the spacing scale, audits the current directory and prints a config to paste.
 
 Commands:
+  quickstart    Same as running with no command
   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
@@ -14,22 +18,24 @@ Options:
   --help        Show this help message
 
 Examples:
+  npx rhythmguard
   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') {
+if (command === '--help' || command === '-h') {
   process.stdout.write(HELP);
   process.exit(0);
 }
 
-if (command === 'audit') {
+if (!command || command === 'quickstart') {
+  require('./quickstart').run();
+} else if (command === 'audit') {
   require('./audit').run();
 } else if (command === 'init') {
-  require('./init');
+  require('./init').run();
 } else if (command === 'doctor') {
   require('./doctor');
 } else {

package/src/cli/init.js

@@ -153,4 +153,8 @@ async function run() {
   }
 }
 
-run();
+module.exports = { detect, run, selectProfile };
+
+if (require.main === module) {
+  run();
+}

package/src/cli/quickstart.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * `npx rhythmguard` with no arguments.
+ *
+ * The first minute, with nothing to configure: detect the stack and any token
+ * files, infer the spacing scale from the project's own tokens, audit the
+ * current directory, and end with the exact config to paste. Never fails the
+ * process on findings; this is a report, not a gate.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { createAuditReport } = require('../audit/report');
+const { detect } = require('./init');
+
+const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
+const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];
+const MAX_LISTED = 5;
+
+function readPackage(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function tailwindMajor(pkg) {
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps['@tailwindcss/postcss'] || deps['@tailwindcss/vite']) {
+    return 4;
+  }
+  const spec = deps.tailwindcss;
+  if (!spec) {
+    return null;
+  }
+  const match = String(spec).match(/(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function findTokenFiles(cwd) {
+  const found = new Set();
+  const consider = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && TOKEN_FILE_PATTERN.test(entry.name)) {
+        found.add(path.relative(cwd, path.join(dir, entry.name)));
+      }
+    }
+  };
+  consider(cwd);
+  for (const sub of TOKEN_DIRS) {
+    consider(path.join(cwd, sub));
+  }
+  return Array.from(found).sort();
+}
+
+function hasRhythmguardConfig(cwd) {
+  return fs.existsSync(path.join(cwd, '.rhythmguardrc.json'));
+}
+
+function toPosix(relativePath) {
+  return `./${relativePath.split(path.sep).join('/')}`;
+}
+
+function topEntries(counts, limit = MAX_LISTED) {
+  return Object.entries(counts || {})
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit);
+}
+
+function suggestedStylelintConfig({ profile, tokenFiles }) {
+  const ruleOptions = { scale: 'auto' };
+  if (tokenFiles.length > 0) {
+    ruleOptions.scaleSources = tokenFiles.map(toPosix);
+  }
+  return {
+    extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+    rules: {
+      'rhythmguard/use-scale': [true, ruleOptions],
+    },
+  };
+}
+
+function eslintSnippet(scaleValues) {
+  const scale = scaleValues.filter((value) => typeof value === 'number').join(', ');
+  return [
+    "// eslint.config.js",
+    "import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';",
+    '',
+    'export default [',
+    '  {',
+    "    plugins: { 'rhythmguard-tailwind': rhythmguard },",
+    `    rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['warn', { scale: [${scale}] }] },`,
+    '  },',
+    '];',
+  ].join('\n');
+}
+
+function describeScale(scale) {
+  if (!scale) {
+    return 'default';
+  }
+  const files = scale.files && scale.files.length > 0 ? ` (${scale.files.slice(0, 3).join(', ')}${scale.files.length > 3 ? ', …' : ''})` : '';
+  return `${scale.source}${files}`;
+}
+
+async function run() {
+  const cwd = process.cwd();
+  const pkg = readPackage(cwd);
+  const stack = detect();
+  const twMajor = stack.tailwind ? tailwindMajor(pkg) : null;
+  const tokenFiles = findTokenFiles(cwd);
+  const rcPresent = hasRhythmguardConfig(cwd);
+  const out = [];
+
+  out.push('', '  Rhythmguard quickstart', `  ${cwd}`, '');
+  out.push('  Detected');
+  out.push(`    Tailwind        ${stack.tailwind ? `v${twMajor || '?'}` : 'no'}`);
+  out.push(`    Next.js         ${stack.nextjs ? 'yes' : 'no'}`);
+  out.push(`    Stylelint config ${stack.hasExistingConfig ? 'present' : 'none'}`);
+  out.push(`    Token files     ${tokenFiles.length > 0 ? tokenFiles.join(', ') : 'none found'}`);
+  out.push(`    .rhythmguardrc  ${rcPresent ? 'present (its token sources are used)' : 'none'}`);
+  out.push('');
+
+  let report;
+  try {
+    report = await createAuditReport({
+      dir: '.',
+      scale: 'auto',
+      ...(tokenFiles.length > 0 && !rcPresent
+        ? { tokenSources: tokenFiles }
+        : {}),
+    });
+  } catch (error) {
+    process.stderr.write(`Quickstart could not audit ${cwd}: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0) {
+    out.push('  No CSS files found here. Run from your project root, or audit a directory directly:');
+    out.push('    npx rhythmguard audit ./src', '');
+    process.stdout.write(`${out.join('\n')}\n`);
+    return;
+  }
+
+  const scale = report.scale;
+  out.push('  Scale');
+  out.push(`    Scale           ${scale.values.join(', ')}`);
+  out.push(`    Source          ${describeScale(scale)}`);
+  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.');
+  }
+  out.push('');
+
+  const offScale = report.findings.css.filter((finding) => finding.type === 'off-scale');
+  out.push('  Findings');
+  out.push(`    CSS files       ${report.cssFilesScanned}`);
+  out.push(`    Template files  ${report.templateFilesScanned}`);
+  out.push(`    Off-scale       ${offScale.length} in CSS, ${report.findings.tailwind.length} in class strings`);
+  out.push(`    Token opps      ${report.findings.css.length - offScale.length} raw values that match or deserve a token`);
+  out.push(`    Cleanliness     ${report.scaleCleanliness}%`);
+  const topValues = topEntries(report.offScaleValues);
+  if (topValues.length > 0) {
+    out.push(`    Top values      ${topValues.map(([value, count]) => `${value} ×${count}`).join(', ')}`);
+  }
+  const topFiles = (report.topAffectedFiles || []).slice(0, 3);
+  if (topFiles.length > 0) {
+    out.push(`    Top files       ${topFiles.map((entry) => `${entry.file} (${entry.count})`).join(', ')}`);
+  }
+  out.push('');
+
+  const profile = stack.tailwind ? (stack.nextjs ? 'react-tailwind' : 'tailwind') : 'recommended';
+  out.push(`  Paste this into .stylelintrc.json${stack.hasExistingConfig ? ' (merge with your existing config)' : ''}:`, '');
+  out.push(JSON.stringify(suggestedStylelintConfig({ profile, tokenFiles }), null, 2).replace(/^/gm, '    '));
+  out.push('');
+
+  if (stack.tailwind) {
+    out.push('  Tailwind class strings need the ESLint companion. Paste this into eslint.config.js:', '');
+    out.push(eslintSnippet(scale.values).replace(/^/gm, '    '));
+    out.push('');
+  }
+
+  out.push('  Next');
+  out.push('    npx stylelint "**/*.css"                      lint with the config above');
+  out.push('    npx rhythmguard audit . --format markdown     PR-ready report');
+  out.push('    npx rhythmguard audit . --write-baseline      then gate only new drift in CI');
+  out.push('    npx rhythmguard doctor                        check the setup');
+  out.push('');
+
+  process.stdout.write(`${out.join('\n')}\n`);
+}
+
+module.exports = { findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };

package/src/configs/embed.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * The one-liner for shared-config authors.
+ *
+ * One rule, warning level, scale inferred from the consuming project's own
+ * spacing tokens (scaleSources, .rhythmguardrc.json token sources, the
+ * stylesheet's custom properties, a Tailwind config, then rhythmic-4).
+ * No `extends`, no dependency beyond this plugin, and the shape is frozen for
+ * the life of the 2.x line so a config that embeds it never changes behaviour
+ * on a minor bump.
+ */
+module.exports = {
+  plugins: ['stylelint-plugin-rhythmguard'],
+  rules: {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        scale: 'auto',
+        severity: 'warning',
+      },
+    ],
+  },
+};

package/src/configs/embed.mjs

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

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

@@ -76,6 +76,7 @@ function buildMessage(analysis, segment, lower, upper) {
 module.exports = {
   meta: {
     docs: {
+      url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-motion-scale.md',
       description: 'Enforce duration scale for Tailwind arbitrary motion utilities in class strings',
     },
     fixable: 'code',

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

@@ -67,6 +67,7 @@ function maybeCheckNodeText(node, sourceCode, context, analyzer, allowFix) {
 module.exports = {
   meta: {
     docs: {
+      url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/tailwind-class-use-scale.md',
       description: 'Enforce spacing scale for Tailwind arbitrary spacing utilities in class strings',
     },
     fixable: 'code',

package/src/index.js

@@ -15,6 +15,7 @@ module.exports.rules = {
   [useMotionScale.ruleName]: useMotionScale,
 };
 module.exports.configs = {
+  embed: require('./configs/embed'),
   recommended: require('./configs/recommended'),
   strict: require('./configs/strict'),
   tailwind: require('./configs/tailwind'),
@@ -22,6 +23,7 @@ module.exports.configs = {
   logical: require('./configs/logical'),
   migration: require('./configs/migration'),
   motion: require('./configs/motion'),
+  'react-tailwind': require('./configs/react-tailwind'),
 };
 module.exports.eslint = require('./eslint');
 module.exports.presets = require('./presets');

package/src/rules/no-offscale-transform/index.js

@@ -5,6 +5,7 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,
@@ -25,6 +26,11 @@ const {
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/no-offscale-transform';
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
@@ -84,6 +90,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    if (options.scaleAuto) {
+      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;
+    }
+
     const scaleCache = new Map();
     const getScaleStateForProperty = (prop) => {
       const cached = scaleCache.get(prop);
@@ -152,6 +170,10 @@ const ruleFunction = (primary, secondaryOptions) => {
           return;
         }
 
+        if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
+          return;
+        }
+
         if (!options.allowNegative && parsedLength.number < 0) {
           return;
         }
@@ -269,7 +291,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguardno-offscale-transform',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/no-offscale-transform.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

package/src/rules/prefer-token/index.js

@@ -4,6 +4,7 @@ const stylelint = require('stylelint');
 const valueParser = require('postcss-value-parser');
 const {
   formatLength,
+  isHairlineLength,
   normalizeScale,
   normalizeScaleByUnit,
   numbersEqual,
@@ -28,6 +29,11 @@ const {
 } = require('../../utils/value-utils');
 const { buildEffectiveTokenMap } = require('../../utils/token-map');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/prefer-token';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
@@ -112,6 +118,18 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    if (options.scaleAuto) {
+      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;
+    }
+
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const tokenMap = buildEffectiveTokenMap({
       options,
@@ -196,6 +214,16 @@ const ruleFunction = (primary, secondaryOptions) => {
           return false;
         }
 
+        // Percentages are relative to the container or the element itself; they are
+        // never spacing-token candidates (translate(-50%, -50%) centering, inset: 100%).
+        if (parsedLength.unit === '%') {
+          return false;
+        }
+
+        if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
+          return false;
+        }
+
         if (
           parsedLength.unit &&
           parsedLength.unit !== '%' &&
@@ -288,7 +316,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguardprefer-token',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/prefer-token.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

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

@@ -236,7 +236,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-motion-scale',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/use-motion-scale.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

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

@@ -5,6 +5,7 @@ const valueParser = require('postcss-value-parser');
 const {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,
@@ -29,13 +30,19 @@ const {
   walkTransformTranslateNodes,
 } = require('../../utils/value-utils');
 
+const {
+  DEFAULT_AUTO_TOKEN_PATTERN,
+  autoScaleFallbackNote,
+  resolveAutoScale,
+} = require('../../utils/scale-inference');
+
 const ruleName = 'rhythmguard/use-scale';
 
 const messages = stylelint.utils.ruleMessages(ruleName, {
   invalidPreset: (presetName, presetNames) =>
     `Unknown scale preset "${presetName}". Available presets: ${presetNames.join(', ')}.`,
-  rejected: (value, lower, upper) =>
-    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).`,
+  rejected: (value, lower, upper, note = '') =>
+    `Unexpected off-scale value "${value}". Use scale values (nearest: ${lower} or ${upper}).${note ? ` ${note}` : ''}`,
 });
 
 function getFixedNodeValue(parsedLength, nearestPx, options) {
@@ -82,7 +89,16 @@ function checkLengthValue({
     return false;
   }
 
-  if (parsedLength.unit === '%' && options.allowPercentages) {
+  if (parsedLength.unit === '%') {
+    if (options.allowPercentages) {
+      return false;
+    }
+
+    report(node.value, decl, node, null, null, '%');
+    return false;
+  }
+
+  if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
     return false;
   }
 
@@ -180,8 +196,21 @@ const ruleFunction = (primary, secondaryOptions) => {
       });
     }
 
+    if (options.scaleAuto) {
+      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;
+    }
+
     const tokenRegex = createTokenRegex(options.tokenPattern, result, ruleName);
     const scaleCache = new Map();
+    let fallbackNote = autoScaleFallbackNote(options.scaleInference);
 
     const getScaleStateForProperty = (prop) => {
       const cached = scaleCache.get(prop);
@@ -208,7 +237,7 @@ const ruleFunction = (primary, secondaryOptions) => {
       const payload = {
         endIndex,
         index,
-        message: messages.rejected(value, lower, upper),
+        message: messages.rejected(value, lower, upper, fallbackNote),
         node: decl,
         result,
         ruleName,
@@ -221,6 +250,7 @@ const ruleFunction = (primary, secondaryOptions) => {
         };
       }
 
+      fallbackNote = '';
       stylelint.utils.report(payload);
     };
 
@@ -332,7 +362,7 @@ ruleFunction.ruleName = ruleName;
 ruleFunction.messages = messages;
 ruleFunction.meta = {
   fixable: true,
-  url: 'https://github.com/petrilahdelma/stylelint-plugin-rhythmguard#rhythmguarduse-scale',
+  url: 'https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/blob/main/docs/rules/use-scale.md',
 };
 
 module.exports = stylelint.createPlugin(ruleName, ruleFunction);

package/src/utils/length.js

@@ -25,6 +25,21 @@ function parseLengthToken(rawValue) {
   return { number, raw: value, unit };
 }
 
+/**
+ * A hairline is a non-zero length that resolves to one CSS pixel or less:
+ * 1px, -1px, 0.5px, 0.0625rem. Such values compensate for a border width or a
+ * rendering quirk; they are not spacing decisions, so the scale rules exempt
+ * them by default (`allowHairlines`).
+ */
+function isHairlineLength(parsedLength, baseFontSize) {
+  if (!parsedLength || parsedLength.number === 0 || parsedLength.unit === '%') {
+    return false;
+  }
+
+  const px = toPx(Math.abs(parsedLength.number), parsedLength.unit || 'px', baseFontSize);
+  return px !== null && px > 0 && px <= 1;
+}
+
 function toPx(number, unit, baseFontSize) {
   if (unit === '' || unit === 'px') {
     return number;
@@ -168,6 +183,7 @@ function nearestScaleValues(target, scale) {
 module.exports = {
   formatLength,
   fromPx,
+  isHairlineLength,
   nearestScaleValues,
   normalizeScale,
   normalizeScaleByUnit,