stylelint-plugin-rhythmguard 3.3.0 → 3.5.0

package/src/audit/contract.js

@@ -3,10 +3,10 @@
 const fs = require('node:fs');
 const {
   addDefinition,
-  collectScssTokens,
+  collectCssTokens,
   createTokenKindMatcher,
   getNormalizedValueKeys,
-} = require('../utils/token-sources');
+} = require('../core/token-sources');
 const { formatPath } = require('./shared');
 
 function collectTokenContract({
@@ -95,33 +95,10 @@ function collectTokenContract({
   };
 }
 
+/** Custom properties and Sass tokens declared in one stylesheet, added to the definitions map. */
 function collectTokenDefinitions(source, file, definitions, matchesKind, baseFontSize) {
-  const declarationPattern = /(--[\w-]+)\s*:\s*([^;{}]+)/g;
-  let match;
-
-  while ((match = declarationPattern.exec(source)) !== null) {
-    const token = match[1];
-    if (!matchesKind(token)) {
-      continue;
-    }
-
-    addDefinition(definitions, {
-      baseFontSize,
-      file,
-      source: file,
-      token,
-      value: match[2].trim(),
-    });
-  }
-
-  for (const sassToken of collectScssTokens(source, matchesKind)) {
-    addDefinition(definitions, {
-      baseFontSize,
-      file,
-      source: file,
-      token: sassToken.token,
-      value: sassToken.value,
-    });
+  for (const { scope, token, value } of collectCssTokens(source, matchesKind)) {
+    addDefinition(definitions, { baseFontSize, file, scope, source: file, token, value });
   }
 }
 

package/src/audit/index.js

@@ -1,12 +1,9 @@
 'use strict';
 
-const {
-  AUDIT_JSON_SCHEMA,
-  createAuditReport,
-  loadAuditConfig,
-  toAuditContractReport,
-} = require('../cli/audit');
-const { parseTokenSources } = require('../utils/token-sources');
+const { loadAuditConfig } = require('./config');
+const { AUDIT_JSON_SCHEMA, toAuditContractReport } = require('./contract');
+const { createAuditReport } = require('./report');
+const { parseTokenSources } = require('../core/token-sources');
 
 module.exports = {
   AUDIT_JSON_SCHEMA,

package/src/audit/report.js

@@ -5,7 +5,7 @@ const fs = require('node:fs');
 const {
   createTokenKindMatcher,
   parseTokenSources,
-} = require('../utils/token-sources');
+} = require('../core/token-sources');
 const {
   applyBaselineComparison,
   writeBaseline,
@@ -19,15 +19,14 @@ const {
 const { buildReport, collectTokenDefinitions } = require('./contract');
 const { DEFAULT_SCALE, formatPath } = require('./shared');
 const {
-  assessScale, discoverTokenPackages, scaleFromDefinitions } = require('../utils/scale-inference');
-const {
-  assertDirectory,
-  collectCssFindings,
-  collectTailwindFindings,
-  collectTailwindMotionFindings,
-  getScanFiles,
-  runStylelintAudit,
-} = require('./scan');
+  assessScale,
+  discoverTokenPackages,
+  inferScaleFromDefinitions,
+  scaleFromDefinitions,
+} = require('../core/scale-inference');
+const { assertDirectory, getScanFiles } = require('./scan/files');
+const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
+const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
 
 async function createAuditReport(options) {
   const parsed = normalizeCreateAuditOptions(options);
@@ -149,10 +148,11 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
   }
 
   if (definitions.size > 0) {
-    const values = scaleFromDefinitions(definitions, baseFontSize);
-    if (values) {
+    const inferred = inferScaleFromDefinitions(definitions, baseFontSize);
+    if (inferred) {
+      const { values } = inferred;
       const files = new Set();
-      for (const definition of definitions.values()) {
+      for (const definition of inferred.definitions.values()) {
         for (const file of definition.files) {
           files.add(file);
         }
@@ -163,7 +163,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
         return {
           files: sortedFiles,
           source: 'scanned-css',
-          tokenCount: definitions.size,
+          tokenCount: inferred.definitions.size,
           values,
         };
       }

package/src/audit/scan/files.js

@@ -0,0 +1,262 @@
+'use strict';
+
+/**
+ * Which files the audit looks at: directory walking, ignore patterns (root-relative
+ * paths and globs), git-scoped selection (--since, --staged), and the file-type
+ * predicates. Nothing here parses CSS.
+ */
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const {
+  SKIP_DIRS,
+  TEMPLATE_EXTENSIONS,
+} = require('../shared');
+
+function assertDirectory(dir) {
+  if (!dir) {
+    throw new Error('Missing audit directory.');
+  }
+
+  const resolvedDir = path.resolve(dir);
+  if (!fs.existsSync(resolvedDir)) {
+    throw new Error(`Directory not found: ${dir}`);
+  }
+
+  if (!fs.statSync(resolvedDir).isDirectory()) {
+    throw new Error(`Not a directory: ${dir}`);
+  }
+
+  return resolvedDir;
+}
+
+function walkFiles(rootDir, ignorePatterns = []) {
+  const cssFiles = [];
+  const templateFiles = [];
+  const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
+
+  function walk(currentDir) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relativePath = toPosixRelativePath(rootDir, fullPath);
+
+      if (shouldIgnorePath(relativePath, entry, ignoreMatchers)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        if (isCssFile(fullPath)) {
+          cssFiles.push(fullPath);
+        } else if (isTemplateFile(fullPath)) {
+          templateFiles.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(rootDir);
+  return { cssFiles, templateFiles };
+}
+
+function getScanFiles(rootDir, ignorePatterns, parsed) {
+  if (parsed.staged || parsed.since) {
+    return getGitChangedScanFiles(rootDir, ignorePatterns, parsed);
+  }
+
+  return {
+    ...walkFiles(rootDir, ignorePatterns),
+    scanScope: {
+      mode: 'full',
+    },
+  };
+}
+
+function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
+  const args = parsed.staged
+    ? ['diff', '--name-only', '--cached', '--diff-filter=ACMR', '--']
+    : ['diff', '--name-only', '--diff-filter=ACMR', parsed.since, '--'];
+  let output = '';
+
+  try {
+    output = execFileSync('git', args, {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const stderr = err.stderr ? String(err.stderr).trim() : err.message;
+    throw new Error(`Unable to read changed files from git: ${stderr}`);
+  }
+
+  const cssFiles = [];
+  const templateFiles = [];
+  const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
+  const seen = new Set();
+  const changedFiles = output.split(/\r?\n/)
+    .map((filePath) => filePath.trim())
+    .filter(Boolean);
+
+  for (const filePath of changedFiles) {
+    const fullPath = path.resolve(process.cwd(), filePath);
+
+    if (!isPathInside(rootDir, fullPath) || seen.has(fullPath) || !fs.existsSync(fullPath)) {
+      continue;
+    }
+
+    const stat = fs.statSync(fullPath);
+    if (!stat.isFile()) {
+      continue;
+    }
+
+    const relativePath = toPosixRelativePath(rootDir, fullPath);
+    if (shouldIgnoreRelativeFile(relativePath, ignoreMatchers)) {
+      continue;
+    }
+
+    seen.add(fullPath);
+    if (isCssFile(fullPath)) {
+      cssFiles.push(fullPath);
+    } else if (isTemplateFile(fullPath)) {
+      templateFiles.push(fullPath);
+    }
+  }
+
+  return {
+    cssFiles,
+    scanScope: {
+      changedFiles: changedFiles.length,
+      mode: parsed.staged ? 'staged' : 'since',
+      since: parsed.since,
+    },
+    templateFiles,
+  };
+}
+
+function isPathInside(rootDir, filePath) {
+  const relativePath = path.relative(rootDir, filePath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function shouldIgnorePath(relativePath, entry, ignoreMatchers) {
+  return ignoreMatchers.some((matcher) => matcher.test(relativePath))
+    || (entry.isDirectory() && SKIP_DIRS.has(entry.name));
+}
+
+function shouldIgnoreRelativeFile(relativePath, ignoreMatchers) {
+  const segments = relativePath.split('/');
+  return segments.some((segment) => SKIP_DIRS.has(segment))
+    || ignoreMatchers.some((matcher) => matcher.test(relativePath));
+}
+
+function createIgnoreMatchers(patterns) {
+  const variants = new Set();
+
+  for (const pattern of patterns) {
+    addIgnorePatternVariants(variants, pattern);
+  }
+
+  return Array.from(variants, (pattern) => globToRegExp(pattern));
+}
+
+function addIgnorePatternVariants(variants, pattern) {
+  if (!pattern) {
+    return;
+  }
+
+  variants.add(pattern);
+
+  if (!pattern.includes('/')) {
+    variants.add(`${pattern}/**`);
+    variants.add(`**/${pattern}`);
+    variants.add(`**/${pattern}/**`);
+    return;
+  }
+
+  if (pattern.endsWith('/**')) {
+    variants.add(pattern.slice(0, -3));
+    return;
+  }
+
+  if (!hasGlob(pattern)) {
+    variants.add(`${pattern}/**`);
+  }
+}
+
+function hasGlob(pattern) {
+  return /[*?]/.test(pattern);
+}
+
+function globToRegExp(pattern) {
+  let source = '^';
+
+  for (let index = 0; index < pattern.length; index++) {
+    const char = pattern[index];
+    const nextChar = pattern[index + 1];
+
+    if (char === '*' && nextChar === '*') {
+      source += '.*';
+      index++;
+      continue;
+    }
+
+    if (char === '*') {
+      source += '[^/]*';
+      continue;
+    }
+
+    if (char === '?') {
+      source += '[^/]';
+      continue;
+    }
+
+    source += escapeRegExp(char);
+  }
+
+  return new RegExp(`${source}$`);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&');
+}
+
+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 too;
+// whether .scss can be parsed is decided when the run starts (stylesheets.js).
+function isCssFile(filePath) {
+  return filePath.endsWith('.css') || isScssFile(filePath);
+}
+
+function isTemplateFile(filePath) {
+  return TEMPLATE_EXTENSIONS.has(path.extname(filePath));
+}
+
+module.exports = {
+  addIgnorePatternVariants,
+  assertDirectory,
+  createIgnoreMatchers,
+  escapeRegExp,
+  getGitChangedScanFiles,
+  getScanFiles,
+  globToRegExp,
+  hasGlob,
+  isCssFile,
+  isPathInside,
+  isScssFile,
+  isTemplateFile,
+  shouldIgnorePath,
+  shouldIgnoreRelativeFile,
+  toPosixRelativePath,
+  walkFiles,
+};

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,
+};