stylelint-plugin-rhythmguard 2.2.0 → 3.1.0

package/src/audit/scan.js

@@ -230,8 +230,33 @@ function toPosixRelativePath(rootDir, filePath) {
   return path.relative(rootDir, filePath).split(path.sep).join('/');
 }
 
+function isScssFile(filePath) {
+  return filePath.endsWith('.scss');
+}
+
+// "CSS files" in the audit means authored stylesheets: .css always, .scss when
+// postcss-scss can be resolved (see resolveScssSyntax).
 function isCssFile(filePath) {
-  return filePath.endsWith('.css');
+  return filePath.endsWith('.css') || isScssFile(filePath);
+}
+
+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;
 }
 
 function isTemplateFile(filePath) {
@@ -240,7 +265,10 @@ function isTemplateFile(filePath) {
 
 async function runStylelintAudit(cssFiles, options) {
   if (cssFiles.length === 0) {
-    return [];
+    const empty = [];
+    empty.scssFiles = 0;
+    empty.scssSkipped = 0;
+    return empty;
   }
 
   const { default: stylelint } = await import('stylelint');
@@ -274,23 +302,52 @@ async function runStylelintAudit(cssFiles, options) {
     ];
   }
 
-  const result = await stylelint.lint({
-    files: cssFiles,
-    config: {
-      plugins: [pluginPath],
-      rules,
-    },
-  });
+  const plainFiles = cssFiles.filter((file) => !isScssFile(file));
+  const scssFiles = cssFiles.filter(isScssFile);
+  const results = [];
 
-  return result.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) "([^"]+)"/,
       );
@@ -308,6 +365,9 @@ function collectCssFindings(fileResults) {
         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 }),
@@ -324,6 +384,73 @@ function collectCssFindings(fileResults) {
   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,
@@ -526,6 +653,7 @@ module.exports = {
   collectTailwindMotionFindings,
   createIgnoreMatchers,
   escapeRegExp,
+  findDeclarationProperty,
   findStringLiterals,
   getCssFindingType,
   getCssFindingValue,
@@ -535,6 +663,8 @@ module.exports = {
   globToRegExp,
   hasGlob,
   isCssFile,
+  isScssFile,
+  resolveScssSyntax,
   isPathInside,
   isTemplateFile,
   offsetToLineColumn,

package/src/cli/init.js

@@ -92,9 +92,6 @@ function detect() {
 }
 
 function selectProfile(stack) {
-  if (stack.nextjs && stack.tailwind) {
-    return 'react-tailwind';
-  }
   if (stack.tailwind) {
     return 'tailwind';
   }
@@ -140,6 +137,8 @@ async function run() {
 
     const config = {
       extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+      // Next.js build output is generated CSS; never lint it.
+      ...(stack.nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
     };
 
     const configPath = path.join(process.cwd(), '.stylelintrc.json');

package/src/cli/quickstart.js

@@ -14,6 +14,7 @@ const path = require('node:path');
 
 const { createAuditReport } = require('../audit/report');
 const { detect } = require('./init');
+const { discoverTokenPackages } = require('../utils/scale-inference');
 
 const TOKEN_FILE_PATTERN = /(^|[.-])tokens?\.json$/i;
 const TOKEN_DIRS = ['tokens', 'design-tokens', path.join('src', 'tokens'), path.join('dist', 'tokens')];
@@ -76,13 +77,14 @@ function topEntries(counts, limit = MAX_LISTED) {
     .slice(0, limit);
 }
 
-function suggestedStylelintConfig({ profile, tokenFiles }) {
+function suggestedStylelintConfig({ nextjs = false, profile, tokenFiles }) {
   const ruleOptions = { scale: 'auto' };
   if (tokenFiles.length > 0) {
     ruleOptions.scaleSources = tokenFiles.map(toPosix);
   }
   return {
     extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+    ...(nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
     rules: {
       'rhythmguard/use-scale': [true, ruleOptions],
     },
@@ -127,6 +129,8 @@ async function run() {
   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'}`);
+  const tokenPackages = [...new Set(discoverTokenPackages(cwd).map((source) => source.package))];
+  out.push(`    Token packages  ${tokenPackages.length > 0 ? tokenPackages.join(', ') : 'none installed'}`);
   out.push(`    .rhythmguardrc  ${rcPresent ? 'present (its token sources are used)' : 'none'}`);
   out.push('');
 
@@ -173,15 +177,19 @@ async function run() {
   if (topValues.length > 0) {
     out.push(`    Top values      ${topValues.map(([value, count]) => `${value} ×${count}`).join(', ')}`);
   }
+  const topProperties = topEntries(report.offScaleProperties);
+  if (topProperties.length > 0) {
+    out.push(`    Top properties  ${topProperties.map(([property, count]) => `${property} ×${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';
+  const profile = stack.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(JSON.stringify(suggestedStylelintConfig({ nextjs: stack.nextjs, profile, tokenFiles }), null, 2).replace(/^/gm, '    '));
   out.push('');
 
   if (stack.tailwind) {

package/src/index.js

@@ -19,11 +19,7 @@ module.exports.configs = {
   recommended: require('./configs/recommended'),
   strict: require('./configs/strict'),
   tailwind: require('./configs/tailwind'),
-  expanded: require('./configs/expanded'),
-  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/utils/scale-inference.js

@@ -5,7 +5,7 @@ const path = require('node:path');
 
 const { parseLengthToken, toPx } = require('./length');
 const { buildEffectiveTokenMap } = require('./token-map');
-const { parseTokenSources } = require('./token-sources');
+const { collectScssTokens, createTokenKindMatcher, parseTokenSources } = require('./token-sources');
 const { getScalePreset } = require('../presets/scales');
 
 // Matches the audit default so lint and audit agree on what a spacing token is.
@@ -21,6 +21,80 @@ const MIN_INFERRED_SCALE_LENGTH = 4;
 const RC_FILE = '.rhythmguardrc.json';
 
 const sourceCache = new Map();
+const TOKEN_PACKAGES = require('./token-packages.json').packages;
+
+/**
+ * Installed design-token packages that ship a spacing scale (allowlist in
+ * token-packages.json). Resolved from the project, so only what the project
+ * actually depends on is read. Returns token-source entries.
+ */
+function readDirectDependencies(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return new Set([
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+    ]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project roots from cwd up to the repository boundary (first directory holding
+ * .git), each with the dependencies it declares directly. Hoisted monorepo
+ * installs are found by walking up; a stray global node_modules is never
+ * consulted because the walk stops at the repository.
+ */
+function projectRoots(cwd) {
+  const roots = [];
+  let current = path.resolve(cwd);
+  for (;;) {
+    const direct = readDirectDependencies(current);
+    if (direct) {
+      roots.push({ dir: current, direct });
+    }
+    const parent = path.dirname(current);
+    if (fs.existsSync(path.join(current, '.git')) || parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return roots;
+}
+
+function discoverTokenPackages(cwd = process.cwd()) {
+  const sources = [];
+  const roots = projectRoots(cwd);
+  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
+    // a non-Tailwind project the Tailwind scale.
+    const owner = roots.find((root) => root.direct.has(entry.name));
+    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')));
+    if (!root) {
+      continue;
+    }
+    for (const file of entry.files) {
+      const resolved = path.join(root, file);
+      if (fs.existsSync(resolved)) {
+        sources.push({
+          format: 'auto',
+          package: entry.name,
+          path: resolved,
+          ...(entry.tokenPattern ? { tokenPattern: entry.tokenPattern } : {}),
+        });
+      }
+    }
+  }
+  return sources;
+}
 
 function pxValuesFromKeys(keys, baseFontSize) {
   const values = new Set([0]);
@@ -54,6 +128,7 @@ function normalizeSource(source, baseDir) {
     return {
       format: typeof source.format === 'string' ? source.format : 'auto',
       path: path.resolve(source.baseDir || baseDir, rawPath),
+      ...(source.tokenPattern ? { tokenPattern: source.tokenPattern } : {}),
     };
   }
 
@@ -69,7 +144,7 @@ function cacheKey(sources) {
       } catch {
         // missing file: key still changes when it appears
       }
-      return `${source.path}|${source.format}|${mtime}`;
+      return `${source.path}|${source.format}|${source.tokenPattern || ''}|${mtime}`;
     })
     .join('\n');
 }
@@ -86,13 +161,9 @@ function scaleFromSources(sources, baseFontSize) {
   }
 
   const parsed = parseTokenSources({ baseFontSize, sources: normalized, tokenKind: 'spacing' });
-  const keys = [];
-  for (const definition of parsed.definitions.values()) {
-    keys.push(...definition.normalizedValues);
-  }
-
-  const scale = pxValuesFromKeys(keys, baseFontSize);
-  const outcome = scale.length >= MIN_INFERRED_SCALE_LENGTH
+  // scaleFromDefinitions also expands a bare Tailwind --spacing base into its multiples.
+  const scale = scaleFromDefinitions(parsed.definitions, baseFontSize);
+  const outcome = scale
     ? {
       files: parsed.sources.map((source) => source.file),
       scale,
@@ -157,8 +228,27 @@ function rcTokenSources(cwd) {
     .filter(Boolean);
 }
 
-function scaleFromTokenMap(map, baseFontSize) {
-  const keys = [];
+/**
+ * Sass variables and maps declared in the linted stylesheet itself (postcss-scss
+ * exposes them as declarations whose prop starts with `$`). Evaluated with the
+ * same collector the audit uses; component variables such as $dropdown-spacer
+ * are excluded by the anchored name rule.
+ */
+function sassValuesFromRoot(root) {
+  const lines = [];
+  root.walkDecls((decl) => {
+    if (typeof decl.prop === 'string' && decl.prop.startsWith('$')) {
+      lines.push(`${decl.prop}: ${decl.value};`);
+    }
+  });
+  if (lines.length === 0) {
+    return [];
+  }
+  return collectScssTokens(lines.join('\n'), createTokenKindMatcher('spacing')).map((token) => token.value);
+}
+
+function scaleFromTokenMap(map, baseFontSize, extraKeys = []) {
+  const keys = [...extraKeys];
   const baseKeys = [];
   for (const [key, reference] of Object.entries(map)) {
     const name = String(reference).match(/^var\((--[\w-]+)\)$/);
@@ -206,7 +296,7 @@ function resolveAutoScale({
       root,
       tokenRegex,
     });
-    const scale = scaleFromTokenMap(stylesheetMap, baseFontSize);
+    const scale = scaleFromTokenMap(stylesheetMap, baseFontSize, sassValuesFromRoot(root));
     if (scale) {
       return { files: [], scale, source: 'stylesheet', tokenCount: scale.length - 1, warnings: [] };
     }
@@ -229,6 +319,11 @@ function resolveAutoScale({
     }
   }
 
+  const fromPackages = scaleFromSources(discoverTokenPackages(process.cwd()), baseFontSize);
+  if (fromPackages) {
+    return { source: 'token-package', ...fromPackages };
+  }
+
   return {
     files: [],
     preset: FALLBACK_PRESET,
@@ -250,6 +345,7 @@ function autoScaleFallbackNote(inference) {
 module.exports = {
   DEFAULT_AUTO_TOKEN_PATTERN,
   autoScaleFallbackNote,
+  discoverTokenPackages,
   resolveAutoScale,
   scaleFromDefinitions,
 };

package/src/utils/token-packages.json

@@ -0,0 +1,48 @@
+{
+  "$comment": "Design-token packages whose installed files declare a spacing scale. Used by scale: \"auto\" after the project's own stylesheets are checked. Each entry lists the files to read (relative to the package root) and, when the package does not use space/spacing names, the token pattern to match. Additions welcome; keep them to files that ship in the published package.",
+  "packages": [
+    {
+      "name": "tailwindcss",
+      "files": [
+        "theme.css"
+      ],
+      "note": "Tailwind v4 base multiplier --spacing"
+    },
+    {
+      "name": "@radix-ui/themes",
+      "files": [
+        "tokens.css"
+      ],
+      "note": "--space-1..9 as calc(<px> * var(--scaling))"
+    },
+    {
+      "name": "@mantine/core",
+      "files": [
+        "styles.css"
+      ],
+      "note": "--mantine-spacing-* as calc(<rem> * var(--mantine-scale))"
+    },
+    {
+      "name": "@primer/primitives",
+      "files": [
+        "dist/css/base/size/size.css"
+      ],
+      "tokenPattern": "^--base-size-\\d+$",
+      "note": "Primer names its spacing ladder size"
+    },
+    {
+      "name": "@shopify/polaris-tokens",
+      "files": [
+        "dist/css/styles.css"
+      ],
+      "note": "--p-space-* in rem"
+    },
+    {
+      "name": "@spectrum-css/tokens",
+      "files": [
+        "dist/css/global-vars.css"
+      ],
+      "note": "--spectrum-spacing-* in px"
+    }
+  ]
+}