stylelint-plugin-rhythmguard 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-06
+
+### Added
+
+- Audit findings for CSS declarations carry the declaration's `property`, recovered from the source at the warning position (`null` inside at-rules). Off-scale findings are counted by property in `offScaleProperties`, exposed as `contracts.scale.offScaleProperties`, rendered as a histogram in text, Markdown and HTML output and as a `Top properties` line in the quickstart. Baseline keys and benchmark snapshots are unchanged. ([#64](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/64))
+
+### Changed
+
+- `rhythmguard audit --help` describes what `--scale auto` reads and in which order, SCSS scanning through `postcss-scss`, and the value, property and file breakdowns.
+- CI and release workflows no longer run the full suite on the Stylelint 16.0.0 floor as an allowed-to-fail step; that step produced an error annotation on every green run. The blocking floor suite is unchanged. Actions `checkout` and `setup-node` moved to v5.
+
 ## [3.0.0] - 2026-09-06
 
 Upgrade notes: [`docs/MIGRATING_TO_3.md`](./docs/MIGRATING_TO_3.md).

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=4" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=5" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
   "bin": {
     "rhythmguard": "src/cli/index.js"

package/src/audit/args.js

@@ -37,8 +37,14 @@ Options:
   --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
   --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
   --scale <values|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
-                                 auto infers the scale from token sources, then scanned CSS
+                                 auto infers the scale from token sources, then --space-*/--spacing-*
+                                 custom properties and Sass variables in scanned CSS/SCSS, then
+                                 installed design-token packages, and reports where it came from
   --base-font-size <number>      px base for rem/em conversion (default: 16)
+
+Scans .css files, and .scss files when postcss-scss is installed. Reports drift by
+value, by property and by file; text output prints histograms, markdown is PR-ready,
+json is the stable 2.0 contract.
 `;
 
 function parseArgs(argv) {

package/src/audit/contract.js

@@ -268,6 +268,9 @@ function buildReport({
   const offScaleValues = countByValue(cssFindings
     .filter((finding) => finding.type === 'off-scale' && finding.value)
     .map((finding) => finding.value));
+  const offScaleProperties = countByValue(cssFindings
+    .filter((finding) => finding.type === 'off-scale' && finding.property)
+    .map((finding) => finding.property));
   const tokenOpportunities = countByValue(cssFindings
     .filter((finding) => finding.type === 'token-opportunity' && finding.value)
     .map((finding) => finding.value));
@@ -319,6 +322,7 @@ function buildReport({
       findings: motionFindings.length,
       values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
     },
+    offScaleProperties: Object.fromEntries(sortCountMap(offScaleProperties).slice(0, 10)),
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
     scale: scale || null,
     scaleCleanliness,
@@ -388,6 +392,7 @@ function toAuditContractReport(report) {
       scale: {
         cleanliness: report.scaleCleanliness,
         files: report.scale ? report.scale.files : [],
+        offScaleProperties: report.offScaleProperties || {},
         offScaleValues: report.offScaleValues,
         source: report.scale ? report.scale.source : 'default',
         tokenOpportunities: report.tokenOpportunities,

package/src/audit/render-html.js

@@ -34,6 +34,7 @@ function renderHtml(report) {
     metricHtml('CSS files', report.cssFilesScanned),
     metricHtml('Template files', report.templateFilesScanned),
     '</section>',
+    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) => [
       source.file,

package/src/audit/render-markdown.js

@@ -40,6 +40,7 @@ function renderMarkdown(report) {
   lines.push('');
 
   appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
+  appendMarkdownCounts(lines, 'CSS Off-Scale Properties', report.offScaleProperties, 'Property');
   appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
   appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
@@ -204,8 +205,8 @@ function appendBaselineMarkdown(lines, report) {
   }
 }
 
-function appendMarkdownCounts(lines, title, counts) {
-  const entries = sortCountMap(counts);
+function appendMarkdownCounts(lines, title, counts, label = 'Value') {
+  const entries = sortCountMap(counts || {});
 
   if (entries.length === 0) {
     return;
@@ -213,7 +214,7 @@ function appendMarkdownCounts(lines, title, counts) {
 
   lines.push(`## ${title}`);
   lines.push('');
-  lines.push('| Value | Count |');
+  lines.push(`| ${label} | Count |`);
   lines.push('| --- | ---: |');
   for (const [value, count] of entries) {
     lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);

package/src/audit/render-text.js

@@ -33,6 +33,7 @@ function renderText(report) {
   lines.push('');
 
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
+  appendHistogram(lines, 'CSS OFF-SCALE PROPERTIES', report.offScaleProperties);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
   appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
@@ -145,9 +146,9 @@ function appendBaselineText(lines, report) {
   }
 }
 
-function appendHistogram(lines, title, counts) {
-  const entries = sortCountMap(counts);
-  const total = sumCounts(counts);
+function appendHistogram(lines, title, counts = {}) {
+  const entries = sortCountMap(counts || {});
+  const total = sumCounts(counts || {});
 
   if (entries.length === 0) {
     return;

package/src/audit/scan.js

@@ -342,10 +342,12 @@ async function runStylelintAudit(cssFiles, options) {
 
 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) "([^"]+)"/,
       );
@@ -363,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 }),
@@ -379,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,
@@ -581,6 +653,7 @@ module.exports = {
   collectTailwindMotionFindings,
   createIgnoreMatchers,
   escapeRegExp,
+  findDeclarationProperty,
   findStringLiterals,
   getCssFindingType,
   getCssFindingValue,

package/src/cli/quickstart.js

@@ -177,6 +177,10 @@ 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(', ')}`);

package/types/audit.d.ts

@@ -77,7 +77,8 @@ export interface AuditFinding {
   key?: string;
   line?: number;
   message: string;
-  property?: string;
+  /** CSS property of the declaration, recovered from the source. Null when the position is not inside a declaration. CSS findings only. */
+  property?: string | null;
   rule?: string;
   type: string;
   value?: string;
@@ -113,6 +114,10 @@ export interface AuditReport {
     motion: AuditFinding[];
     tailwind: AuditFinding[];
   };
+  /** Off-scale CSS findings counted by property, top ten. */
+  offScaleProperties?: Record<string, number>;
+  /** Off-scale CSS findings counted by value, top ten. */
+  offScaleValues?: Record<string, number>;
   scanned: AuditScanned;
   summary: AuditSummary;
   [key: string]: unknown;
@@ -130,6 +135,7 @@ export interface AuditContractReport {
     scale: {
       cleanliness?: unknown;
       files: string[];
+      offScaleProperties?: Record<string, number>;
       offScaleValues?: unknown;
       source: AuditScaleSource;
       tokenOpportunities?: unknown;