stylelint-plugin-rhythmguard 3.11.0 → 3.12.0

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

package/src/audit/report.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const fs = require('node:fs');
+const path = require('node:path');
 
 const {
   createTokenKindMatcher,
@@ -27,7 +27,7 @@ const {
 const { applyDecisions, buildDecisionPlan } = require('./decisions');
 const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
 const { resolveTokenLadders, toLaddersContract } = require('./token-ladders');
-const { assertDirectory, getScanFiles } = require('./scan/files');
+const { assertDirectory, getScanFiles, readSourceFromDisk } = require('./scan/files');
 const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
 const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
 
@@ -39,6 +39,8 @@ async function createAuditReport(options) {
   const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
 
   const { cssFiles, scanScope, templateFiles } = scanFiles;
+  // A --staged run reads each changed file as the index holds it.
+  const readSource = scanFiles.readSource || readSourceFromDisk;
 
   const tokenSourceResult = parseTokenSources({
     baseFontSize: parsed.baseFontSize,
@@ -46,23 +48,34 @@ async function createAuditReport(options) {
     tokenKind: parsed.tokenKind,
   });
 
+  // The spacing scale always reads spacing tokens; --token-kind shapes the token contract only (issue #260).
+  const spacingSourceResult = parsed.tokenKind === 'spacing'
+    ? tokenSourceResult
+    : parseTokenSources({ baseFontSize: parsed.baseFontSize, sources: parsed.tokenSources, tokenKind: 'spacing' });
+
   const scale = resolveAuditScale({
     baseFontSize: parsed.baseFontSize,
     cssFiles,
+    readSource,
     requested: parsed.scale,
-    tokenSourceResult,
+    tokenSourceResult: spacingSourceResult,
   });
 
   const lintOptions = {
     baseFontSize: parsed.baseFontSize,
     checkMathBounds: parsed.checkMathBounds,
     includeMotion: parsed.includeMotion,
+    readSource: scanFiles.readSource,
     scale: scale.values,
     scales: parsed.scales,
   };
 
   const cssResults = await runStylelintAudit(cssFiles, lintOptions);
-  const stylelintFindings = collectCssFindings(cssResults);
+  const collectedCssFindings = collectCssFindings(cssResults, readSource);
+  // A stylesheet that failed to parse was not audited; it is reported apart
+  // and is neither a finding nor a clean file.
+  const parseErrorFindings = collectedCssFindings.filter((finding) => finding.type === 'parse-error');
+  const stylelintFindings = collectedCssFindings.filter((finding) => finding.type !== 'parse-error');
   const decided = applyDecisions({
     baseFontSize: parsed.baseFontSize,
     cssFindings: stylelintFindings.filter((finding) => !finding.type.startsWith('motion-')),
@@ -84,6 +97,8 @@ async function createAuditReport(options) {
     externalTokenDefinitions: tokenSourceResult.definitions,
     includeMotion: parsed.includeMotion,
     motionFindings,
+    parseErrorFindings,
+    readSource,
     scale,
     scanScope,
     scssFiles: cssResults.scssFiles || 0,
@@ -100,11 +115,13 @@ async function createAuditReport(options) {
   const declarations = collectDeclarations({
     cssFiles,
     externalDefinitions: tokenSourceResult.definitions,
+    readSource,
     skipFile: (file) => NON_AUTHORED_SEGMENT.test(file),
   });
   report.tokenContract.chains = toChainsContract(resolveTokenChains({
     baseFontSize: parsed.baseFontSize,
     declarations,
+    references: collectDeclarations({ cssFiles: [], externalDefinitions: chainDefinitions(parsed) }),
     scale: scale.values,
   }));
   report.tokenContract.ladders = toLaddersContract(resolveTokenLadders({
@@ -123,17 +140,47 @@ async function createAuditReport(options) {
     scale: scale.values,
   });
 
-  if (parsed.sinceBaseline) {
-    applyBaselineComparison(report, parsed.baselinePath);
-  }
+  if (parsed.sinceBaseline || parsed.writeBaseline) {
+    const unauditedFiles = [
+      ...(cssResults.unauditedFiles || []),
+      ...parseErrorFindings.map((finding) => path.resolve(process.cwd(), finding.file)),
+    ];
+    const unaudited = new Set(unauditedFiles);
+    const baselineScope = {
+      auditedFiles: [...cssFiles, ...templateFiles].filter((file) => !unaudited.has(file)),
+      scanRoot: resolvedDir,
+      scoped: scanScope.mode !== 'full',
+      unauditedFiles,
+    };
 
-  if (parsed.writeBaseline) {
-    writeBaseline(report, parsed.baselinePath);
+    if (parsed.sinceBaseline) {
+      applyBaselineComparison(report, parsed.baselinePath, baselineScope);
+    }
+
+    if (parsed.writeBaseline) {
+      writeBaseline(report, parsed.baselinePath, baselineScope);
+    }
   }
 
   return report;
 }
 
+/**
+ * Every custom property a chain can end in: all tokens in the token sources,
+ * whatever --token-kind says and whatever name pattern a source sets, plus
+ * installed token packages (issue #259). A chain through `--size-8` or a
+ * package's `--space-2` resolves instead of reading "not declared"; these are
+ * looked up only, never reported as chains of their own.
+ */
+function chainDefinitions(parsed) {
+  const unfiltered = (source) => (source && typeof source === 'object' ? { ...source, tokenPattern: null } : source);
+  return parseTokenSources({
+    baseFontSize: parsed.baseFontSize,
+    sources: [...parsed.tokenSources, ...discoverTokenPackages(process.cwd())].map(unfiltered),
+    tokenKind: 'all',
+  }).definitions;
+}
+
 const NON_AUTHORED_SEGMENT = /(^|\/)(test|tests|__tests__|spec|specs|fixtures?|__fixtures__|__snapshots__|vendor|third[-_]?party|storybook-static)(\/|$)/i;
 
 /**
@@ -141,7 +188,7 @@ const NON_AUTHORED_SEGMENT = /(^|\/)(test|tests|__tests__|spec|specs|fixtures?|_
  * "auto": external token sources, then spacing custom properties across the scanned
  * CSS, then the default scale. First source that yields values wins.
  */
-function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResult }) {
+function resolveAuditScale({ baseFontSize, cssFiles, readSource = readSourceFromDisk, requested, tokenSourceResult }) {
   if (Array.isArray(requested)) {
     return {
       files: [],
@@ -174,7 +221,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, requested, tokenSourceResul
     }
     let text;
     try {
-      text = fs.readFileSync(filePath, 'utf8');
+      text = readSource(filePath);
     } catch {
       continue;
     }