stylelint-plugin-rhythmguard 3.10.2 → 3.12.0

package/src/audit/codemod.js

@@ -22,10 +22,21 @@ const { resolveScssSyntax } = require('./scan/stylesheets');
 const TOKEN_FUNCTIONS = ['var', 'theme', 'token'];
 const ANY_TOKEN = /./;
 
-function replaceLength(root, { baseFontSize = 16, properties = null, px, replacement }) {
+/**
+ * Several replacements (`rhythmguard fix --decided`) run in one pass over the
+ * original values: each literal is matched against the list once, and a value
+ * one replacement writes is never matched again, so decisions 10px -> 14px and
+ * 14px -> 16px leave padding: 10px at 14px. The first matching entry wins.
+ */
+function normalizeReplacements({ px, replacement, replacements }) {
+  return Array.isArray(replacements) ? replacements : [{ px, replacement }];
+}
+
+function replaceLength(root, { baseFontSize = 16, properties = null, px, replacement, replacements }) {
   const patterns = properties && properties.length > 0
     ? properties.map((property) => property.toLowerCase())
     : PROPERTY_GROUP_PATTERNS.spacing;
+  const planned = normalizeReplacements({ px, replacement, replacements });
   const changes = [];
 
   root.walkDecls((decl) => {
@@ -48,10 +59,11 @@ function replaceLength(root, { baseFontSize = 16, properties = null, px, replace
         return false;
       }
       const nodePx = toPx(Math.abs(length.number), length.unit, baseFontSize);
-      if (nodePx === null || !numbersEqual(nodePx, px)) {
+      const match = nodePx === null ? null : planned.find((entry) => numbersEqual(nodePx, entry.px));
+      if (!match) {
         return false;
       }
-      const to = length.number < 0 ? negateReplacement(replacement) : replacement;
+      const to = length.number < 0 ? negateReplacement(match.replacement) : match.replacement;
       changes.push({
         column: (decl.source && decl.source.start ? decl.source.start.column : 1) + declarationValueOffset(decl) + node.sourceIndex,
         from: node.value,
@@ -77,46 +89,59 @@ function declarationValueOffset(decl) {
   return decl.prop.length + between.length;
 }
 
+/**
+ * Parse with the syntax that will write the file back. SCSS goes through
+ * postcss-scss's own parse and stringify: `postcss.parse` ignores a `syntax`
+ * option, so it would read `// a: 10px` as a declaration and rewrite it.
+ * Returns null for SCSS when postcss-scss cannot be resolved; such a file is
+ * skipped, never parsed as CSS.
+ */
 function parseStylesheet(filePath, source) {
   if (isScssFile(filePath)) {
     const syntaxPath = resolveScssSyntax();
     if (!syntaxPath) {
       return null;
     }
-    return postcss.parse(source, { from: filePath, syntax: require(syntaxPath) });
+    const syntax = require(syntaxPath);
+    return { root: syntax.parse(source, { from: filePath }), syntax };
   }
-  return postcss.parse(source, { from: filePath });
+  return { root: postcss.parse(source, { from: filePath }), syntax: null };
 }
 
 /**
- * Apply one replacement across a directory. Dry run unless `write`; returns
+ * Apply one replacement (`px` and `replacement`), or several in one pass
+ * (`replacements: [{ px, replacement }]`), across a directory. Dry run unless
+ * `write`; the dry run reports exactly what a write would write. Returns
  * the per-file changes and which files were skipped (unparseable, or SCSS
- * without postcss-scss).
+ * without postcss-scss). `ignorePatterns` are root-relative paths and globs,
+ * as the audit takes them; the audit's generated and vendored directories
+ * (node_modules, dist, build and the rest of SKIP_DIRS) are always skipped.
  */
-function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties = null, px, replacement, write = false }) {
+function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties = null, px, replacement, replacements, write = false }) {
   const rootDir = path.resolve(process.cwd(), dir);
   const files = walkFiles(rootDir, ignorePatterns).cssFiles.filter(isCssFile).sort();
   const results = [];
   const skipped = [];
   for (const filePath of files) {
     const source = fs.readFileSync(filePath, 'utf8');
-    let root;
+    let parsed;
     try {
-      root = parseStylesheet(filePath, source);
+      parsed = parseStylesheet(filePath, source);
     } catch {
       skipped.push({ file: formatPath(filePath), reason: 'could not parse' });
       continue;
     }
-    if (!root) {
-      skipped.push({ file: formatPath(filePath), reason: 'install postcss-scss to rewrite SCSS' });
+    if (!parsed) {
+      skipped.push({ file: formatPath(filePath), reason: 'postcss-scss is not installed; install it to rewrite SCSS' });
       continue;
     }
-    const changes = replaceLength(root, { baseFontSize, properties, px, replacement });
+    const { root, syntax } = parsed;
+    const changes = replaceLength(root, { baseFontSize, properties, px, replacement, replacements });
     if (changes.length === 0) {
       continue;
     }
     if (write) {
-      fs.writeFileSync(filePath, root.toString());
+      fs.writeFileSync(filePath, syntax ? root.toString(syntax) : root.toString());
     }
     results.push({ changes, file: formatPath(filePath) });
   }

package/src/audit/config.js

@@ -4,10 +4,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { normalizeDecisions } = require('../core/decisions');
 const { SCALED_GROUPS, isGroupScalesMap } = require('../core/options');
-const {
-  normalizeTokenKind,
-  normalizeTokenSourceFormat,
-} = require('../core/token-sources');
+const { normalizeTokenKind } = require('../core/token-sources');
+const { normalizeTokenSourceEntry } = require('../core/token-source-entries');
 const {
   parseBaseFontSize,
   parseNonNegativeInteger,
@@ -15,6 +13,7 @@ const {
   parsePercentage,
   parsePositiveInteger,
   parseScale,
+  validateScale,
 } = require('./args');
 const {
   DEFAULT_IGNORE_PATH,
@@ -117,9 +116,9 @@ function applyAuditConfig(parsed, configResult) {
   }
   applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
     if (Array.isArray(value)) {
-      return value;
+      return validateScale(value, 'audit.scale');
     }
-    return parseScale(String(value));
+    return parseScale(String(value), 'audit.scale');
   });
 
   next.decisions = normalizeDecisions(configResult.decisions, { baseFontSize: next.baseFontSize });
@@ -189,33 +188,14 @@ function normalizeConfigTokenSources(sources, baseDir) {
     throw new Error('Invalid Rhythmguard config: audit.tokenSources must be an array.');
   }
 
+  // The lint reads the same entries through the same normaliser, so both see the same files.
   return sources.map((source) => {
-    if (typeof source === 'string') {
-      return {
-        baseDir,
-        format: 'auto',
-        path: source,
-      };
-    }
-
-    if (!source || typeof source !== 'object' || Array.isArray(source)) {
-      throw new Error('Invalid Rhythmguard config: audit.tokenSources entries must be strings or objects.');
-    }
-
-    if (typeof source.path !== 'string' || source.path.trim().length === 0) {
-      throw new Error('Invalid Rhythmguard config: token source objects must include a path.');
+    const { error, source: normalized } = normalizeTokenSourceEntry(source, baseDir);
+    if (error) {
+      // A bad format already reads "Invalid token source format ..."; structural problems name the config.
+      throw new Error(/^Invalid /.test(error) ? error : `Invalid Rhythmguard config: ${error}`);
     }
-
-    if (source.tokenPattern !== undefined && (typeof source.tokenPattern !== 'string' || source.tokenPattern.trim().length === 0)) {
-      throw new Error('Invalid Rhythmguard config: token source tokenPattern must be a non-empty string.');
-    }
-
-    return {
-      baseDir,
-      format: normalizeTokenSourceFormat(source.format || 'auto'),
-      path: source.path,
-      ...(source.tokenPattern ? { tokenPattern: source.tokenPattern } : {}),
-    };
+    return normalized;
   });
 }
 
@@ -240,6 +220,19 @@ function loadIgnorePatterns(ignorePath) {
     .filter(Boolean);
 }
 
+/**
+ * The ignore list a run uses: the ignore file (.rhythmguardignore unless
+ * --ignore-path or audit.ignorePath names another), then audit.ignore and
+ * --ignore. `parsed` is the options after applyAuditConfig. The audit and
+ * `rhythmguard fix` both call this, so they never disagree on what is skipped.
+ */
+function resolveIgnorePatterns(parsed) {
+  return [
+    ...loadIgnorePatterns(parsed.ignorePath),
+    ...parsed.ignorePatterns,
+  ];
+}
+
 module.exports = {
   applyAuditConfig,
   applyConfigScalar,
@@ -248,4 +241,5 @@ module.exports = {
   normalizeCliTokenSources,
   normalizeConfigTokenSources,
   parseBooleanOption,
+  resolveIgnorePatterns,
 };

package/src/audit/contract.js

@@ -6,6 +6,7 @@ const {
   collectCssTokens,
   createTokenKindMatcher,
   getNormalizedValueKeys,
+  hasLineComments,
 } = require('../core/token-sources');
 const { formatPath } = require('./shared');
 
@@ -15,6 +16,7 @@ function collectTokenContract({
   cssFindings,
   externalTokenDefinitions,
   minCandidateCount,
+  readSource = (filePath) => fs.readFileSync(filePath, 'utf8'),
   tailwindFindings,
   tokenKind,
   tokenSourceReports,
@@ -28,7 +30,7 @@ function collectTokenContract({
   for (const filePath of cssFiles) {
     let source;
     try {
-      source = fs.readFileSync(filePath, 'utf8');
+      source = readSource(filePath);
     } catch {
       continue;
     }
@@ -97,7 +99,7 @@ function collectTokenContract({
 
 /** Custom properties and Sass tokens declared in one stylesheet, added to the definitions map. */
 function collectTokenDefinitions(source, file, definitions, matchesKind, baseFontSize) {
-  for (const { scope, token, value } of collectCssTokens(source, matchesKind)) {
+  for (const { scope, token, value } of collectCssTokens(source, matchesKind, { lineComments: hasLineComments(file) })) {
     addDefinition(definitions, { baseFontSize, file, scope, source: file, token, value });
   }
 }
@@ -231,6 +233,8 @@ function buildReport({
   externalTokenDefinitions,
   includeMotion,
   motionFindings,
+  parseErrorFindings = [],
+  readSource,
   scale,
   scanScope,
   scssFiles = 0,
@@ -267,18 +271,24 @@ function buildReport({
     ...tailwindFindings.map((finding) => finding.file),
   ])).slice(0, 10);
 
-  const totalFiles = cssFiles.length + templateFiles.length;
+  // A stylesheet skipped for want of postcss-scss, or excluded by the project's
+  // .stylelintignore, was not audited: it is neither scanned nor clean.
+  const cssFilesScanned = Math.max(0, cssFiles.length - scssSkipped - stylelintIgnored);
+  const totalFiles = cssFilesScanned + templateFiles.length;
   const totalWarnings = cssFindings.length + motionFindings.length + tailwindFindings.length;
   const filesWithIssues = issueFiles.size;
-  const scaleCleanliness = totalFiles > 0
-    ? Math.max(0, Math.round(((totalFiles - filesWithIssues) / totalFiles) * 100))
-    : 100;
+  const scaleCleanliness = Math.floor(computeScaleCleanliness({
+    filesWithIssues,
+    parseErrorFiles: countFiles(parseErrorFindings),
+    totalFiles,
+  }));
   const tokenContract = collectTokenContract({
     baseFontSize,
     cssFiles,
     cssFindings,
     externalTokenDefinitions,
     minCandidateCount: tokenCandidateMinCount,
+    readSource,
     tailwindFindings,
     tokenKind,
     tokenSourceReports,
@@ -286,12 +296,13 @@ function buildReport({
 
   return {
     config,
-    cssFilesScanned: cssFiles.length,
+    cssFilesScanned,
     directory: dir,
     filesWithIssues,
     findings: {
       css: cssFindings,
       motion: motionFindings,
+      parseErrors: parseErrorFindings,
       tailwind: tailwindFindings,
     },
     formatVersion: 5,
@@ -306,7 +317,7 @@ function buildReport({
     scaleCleanliness,
     scanScope,
     scanned: {
-      cssFiles: cssFiles.length,
+      cssFiles: cssFilesScanned,
       scssFiles,
       scssSkipped,
       stylelintIgnored,
@@ -317,6 +328,7 @@ function buildReport({
       cssWarnings: cssFindings.length,
       filesWithIssues,
       motionFindings: motionFindings.length,
+      parseErrors: parseErrorFindings.length,
       rawValueMatches: tokenContract.summary.rawValueMatches,
       missingTokens: tokenContract.summary.missingTokens,
       rawValueCandidates: tokenContract.summary.rawValueCandidates,
@@ -338,6 +350,36 @@ function buildReport({
   };
 }
 
+/**
+ * The share of audited files with no finding, unrounded. A file that failed to
+ * parse was not audited, so it is out of the denominator. The report shows the
+ * floor of this, so it never reads 100% while a file has a finding, and the
+ * --min-cleanliness gate compares this exact value.
+ */
+function computeScaleCleanliness({ filesWithIssues, parseErrorFiles = 0, totalFiles }) {
+  const auditedFiles = totalFiles - parseErrorFiles;
+  if (auditedFiles <= 0) {
+    return 100;
+  }
+  return Math.max(0, ((auditedFiles - filesWithIssues) * 100) / auditedFiles);
+}
+
+/** The unrounded cleanliness of a built report. */
+function exactScaleCleanliness(report) {
+  if (!Number.isFinite(report.totalFiles) || !Number.isFinite(report.filesWithIssues)) {
+    return report.scaleCleanliness;
+  }
+  return computeScaleCleanliness({
+    filesWithIssues: report.filesWithIssues,
+    parseErrorFiles: countFiles((report.findings && report.findings.parseErrors) || []),
+    totalFiles: report.totalFiles,
+  });
+}
+
+function countFiles(findings) {
+  return new Set(findings.map((finding) => finding.file)).size;
+}
+
 function countByValue(values) {
   const counts = {};
 
@@ -395,10 +437,52 @@ const AUDIT_JSON_SCHEMA = Object.freeze({
     baseline: { type: ['object', 'null'] },
     command: { type: 'object' },
     contracts: { type: 'object' },
-    findings: { type: 'object' },
+    findings: {
+      additionalProperties: true,
+      properties: {
+        css: { type: 'array' },
+        motion: { type: 'array' },
+        parseErrors: {
+          description: 'Stylesheets that could not be parsed and so were not audited. Not counted as findings or in cleanliness.',
+          items: {
+            additionalProperties: true,
+            properties: {
+              column: { type: 'integer' },
+              file: { type: 'string' },
+              line: { type: 'integer' },
+              rule: { const: 'CssSyntaxError' },
+              text: { type: 'string' },
+              type: { const: 'parse-error' },
+            },
+            required: ['file', 'text', 'type'],
+            type: 'object',
+          },
+          type: 'array',
+        },
+        tailwind: { type: 'array' },
+      },
+      type: 'object',
+    },
     scanned: { type: 'object' },
     schemaVersion: { const: '2.0' },
-    summary: { type: 'object' },
+    summary: {
+      additionalProperties: true,
+      properties: {
+        parseErrors: {
+          description: 'Number of stylesheets that could not be parsed.',
+          minimum: 0,
+          type: 'integer',
+        },
+        scaleCleanliness: {
+          description: 'Percentage of audited files with no finding, rounded down.',
+          maximum: 100,
+          minimum: 0,
+          type: 'integer',
+        },
+        totalFindings: { minimum: 0, type: 'integer' },
+      },
+      type: 'object',
+    },
   },
   required: ['schemaVersion', 'command', 'summary', 'scanned', 'contracts', 'findings'],
   title: 'Rhythmguard Audit Report',
@@ -414,8 +498,10 @@ module.exports = {
   collectTokenContract,
   collectTokenDefinitions,
   collectTokenUses,
+  computeScaleCleanliness,
   countByValue,
   createValueToTokensMap,
+  exactScaleCleanliness,
   mapTokenEntries,
   sortCountMap,
   sumCounts,

package/src/audit/render-github.js

@@ -7,6 +7,10 @@ function renderGithub(report) {
   const lines = report.baseline
     ? [`::notice title=Rhythmguard audit::Since baseline: ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new`]
     : [];
+  // A stylesheet that failed to parse was not audited: an error on its line.
+  lines.push(...((report.findings && report.findings.parseErrors) || []).map((finding) =>
+    `::error file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'CssSyntaxError')}::${escapeGithubData(`Not audited: ${finding.text || ''}`)}`,
+  ));
   lines.push(...findings.map((finding) =>
     `::warning file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'rhythmguard')}::${escapeGithubData(finding.text || '')}`,
   ));

package/src/audit/render-html.js

@@ -33,7 +33,9 @@ function renderHtml(report) {
     metricHtml('Scale cleanliness', `${report.scaleCleanliness}%`),
     metricHtml('CSS files', report.cssFilesScanned),
     metricHtml('Template files', report.templateFilesScanned),
+    ...(parseErrorRows(report).length > 0 ? [metricHtml('Parse errors (not audited)', parseErrorRows(report).length)] : []),
     '</section>',
+    renderHtmlTable('Parse Errors (not audited)', ['File', 'Error'], parseErrorRows(report)),
     renderHtmlTable('CSS Off-Scale Properties', ['Property', 'Count'], Object.entries(report.offScaleProperties || {})),
     renderHtmlTable('Top Affected Files', ['File', 'Findings'], report.topAffectedFiles.map(({ file, count }) => [file, count])),
     renderHtmlTable('Token Contract Sources', ['File', 'Format', 'Tokens'], report.tokenContract.sources.map((source) => [
@@ -52,6 +54,11 @@ function renderHtml(report) {
   return `${lines.join('\n')}\n`;
 }
 
+function parseErrorRows(report) {
+  return ((report.findings && report.findings.parseErrors) || [])
+    .map((finding) => [`${finding.file}:${finding.line}:${finding.column}`, finding.text]);
+}
+
 function metricHtml(label, value) {
   return `<div class="metric"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></div>`;
 }

package/src/audit/render-markdown.js

@@ -28,6 +28,7 @@ function renderMarkdown(report) {
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
     ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
+    ...(parseErrors(report).length > 0 ? [`| Stylesheets that failed to parse (not audited) | ${parseErrors(report).length} |`] : []),
     `| Files with issues | ${report.filesWithIssues} |`,
     `| Total findings | ${report.totalWarnings} |`,
     `| Scale cleanliness | ${report.scaleCleanliness}% |`,
@@ -57,6 +58,7 @@ function renderMarkdown(report) {
   appendTokenChainsMarkdown(lines, report.tokenContract.chains);
   appendTokenLaddersMarkdown(lines, report.tokenContract.ladders);
   appendBaselineMarkdown(lines, report);
+  appendParseErrorsMarkdown(lines, report);
 
   if (report.topAffectedFiles.length > 0) {
     lines.push('## Top Affected Files');
@@ -82,6 +84,9 @@ function renderMarkdown(report) {
 
   lines.push('## Recommended Next Actions');
   lines.push('');
+  if (parseErrors(report).length > 0) {
+    lines.push('- Fix the parse errors above: those stylesheets were not audited.');
+  }
   if (report.totalWarnings === 0) {
     lines.push('- Keep Rhythmguard in CI to prevent new drift.');
   } else {
@@ -94,6 +99,27 @@ function renderMarkdown(report) {
   return `${lines.join('\n')}\n`;
 }
 
+function parseErrors(report) {
+  return (report.findings && report.findings.parseErrors) || [];
+}
+
+function appendParseErrorsMarkdown(lines, report) {
+  const errors = parseErrors(report);
+  if (errors.length === 0) {
+    return;
+  }
+  lines.push('## Parse Errors');
+  lines.push('');
+  lines.push('These stylesheets could not be parsed, so they were not audited. They are not counted as findings or in scale cleanliness.');
+  lines.push('');
+  lines.push('| File | Error |');
+  lines.push('| --- | --- |');
+  for (const finding of errors) {
+    lines.push(`| \`${escapeMarkdown(`${finding.file}:${finding.line}:${finding.column}`)}\` | ${escapeMarkdown(finding.text)} |`);
+  }
+  lines.push('');
+}
+
 function appendTokenChainsMarkdown(lines, chains) {
   if (!chains || chains.summary.total === 0) {
     return;
@@ -295,6 +321,7 @@ function appendMarkdownCounts(lines, title, counts, label = 'Value') {
 module.exports = {
   appendBaselineMarkdown,
   appendMarkdownCounts,
+  appendParseErrorsMarkdown,
   appendTokenContractMarkdown,
   renderMarkdown,
 };

package/src/audit/render-text.js

@@ -22,6 +22,7 @@ function renderText(report) {
     ...(report.scanned && report.scanned.scssFiles > 0 ? [`  SCSS files scanned       ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
     ...(report.scanned && report.scanned.scssSkipped > 0 ? [`  SCSS files skipped       ${String(report.scanned.scssSkipped).padStart(4)}  (install postcss-scss to audit them)`] : []),
     ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`  Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)}  (not audited)`] : []),
+    ...(parseErrors(report).length > 0 ? [`  Parse errors             ${String(parseErrors(report).length).padStart(4)}  (not audited)`] : []),
     `  Files with issues        ${String(report.filesWithIssues).padStart(4)}`,
     `  Scale cleanliness        ${scoreBar(report.scaleCleanliness)}  ${report.scaleCleanliness}%`,
   ];
@@ -57,6 +58,7 @@ function renderText(report) {
     lines.push('');
   }
   appendBaselineText(lines, report);
+  appendParseErrorsText(lines, report);
 
   if (report.topAffectedFiles.length > 0) {
     lines.push('  ── TOP AFFECTED FILES ──');
@@ -68,7 +70,9 @@ function renderText(report) {
     lines.push('');
   }
 
-  if (report.totalWarnings === 0) {
+  if (report.totalWarnings === 0 && parseErrors(report).length > 0) {
+    lines.push(`  ! No findings in the stylesheets that parsed; ${parseErrors(report).length} could not be parsed and were not audited.`);
+  } else if (report.totalWarnings === 0) {
     lines.push('  ✓ No issues found. Your design-system rhythm is clean.');
   } else {
     lines.push('  → Run "npx stylelint --fix" for CSS declaration fixes.');
@@ -79,6 +83,23 @@ function renderText(report) {
   return `${lines.join('\n')}\n`;
 }
 
+function parseErrors(report) {
+  return (report.findings && report.findings.parseErrors) || [];
+}
+
+function appendParseErrorsText(lines, report) {
+  const errors = parseErrors(report);
+  if (errors.length === 0) {
+    return;
+  }
+  lines.push(`  ── PARSE ERRORS ──  ${errors.length} not audited`);
+  lines.push('');
+  for (const finding of errors) {
+    lines.push(`  ${finding.file}:${finding.line}:${finding.column}  ${finding.text}`);
+  }
+  lines.push('');
+}
+
 function appendTokenContractText(lines, tokenContract) {
   const {
     conflictingTokens,
@@ -184,6 +205,7 @@ function appendHistogram(lines, title, counts = {}) {
 module.exports = {
   appendBaselineText,
   appendHistogram,
+  appendParseErrorsText,
   appendTokenContractText,
   renderText,
 };