stylelint-plugin-rhythmguard 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.8.0] - 2026-09-18
+
+### Added
+
+- `npm run bench:agents`, the agent eval harness: sixteen tasks over three fixture projects, each run as before (no linter), with findings (up to three correction rounds) and rules only (the control), through Sonnet 5, Haiku 4.5 and Opus 5; outcomes, rounds to zero and cost per condition in a dated edition under `docs/agent-evals/`. `--dry-run` exercises the whole pipeline against a scripted model. Method in `docs/AGENT_EVALS.md`. ([#135](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/135))
+- The browser playground runs the real rules. `docs/playground/rhythmguard.js` is an esbuild bundle of the shipped `use-scale`, `prefer-token`, `no-offscale-transform` and `use-motion-scale` with a small Stylelint shim; the page offers `scale: "auto"`, every preset, SCSS, and a fixed-CSS view. A contract test rebuilds the bundle and compares the page's sample against Stylelint, so the playground cannot drift from the plugin again. ([#57](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/57))
+- `use-scale` evaluates Sass expressions in `.scss` declarations: `padding: $spacer * .3` is reported as off scale with `Evaluates to 4.8px.` when `$spacer` resolves from the linted file, `scaleSources`, the config's token sources or an installed package; each term of `padding: $y $x` is checked on its own; `* / + -`, negation, parentheses and `math.div()` are understood. Unresolvable terms are left alone as before, and an expression is never rewritten by `--fix`. The audit inherits it, so SCSS design systems now see drift that hid behind a variable.
+- [`PetriLahdelma/rhythmguard-action`](https://github.com/PetriLahdelma/rhythmguard-action), a GitHub Action that runs the audit, annotates the diff, posts the report as one pull-request comment updated in place, and fails on new drift against a committed baseline. Linked from the README and the CI adoption recipe.
+- `rhythmguard`, the command as its own package: `npx rhythmguard` resolves a package of that name, and none existed, so the first command in the README failed in a project that had installed nothing (`npx stylelint-plugin-rhythmguard` worked, and the README says that until the package is published). `packages/rhythmguard` is one dependency and one line that runs the CLI, now exported as `stylelint-plugin-rhythmguard/cli` with a `main()`.
+- `eslint-plugin-rhythmguard`, the ESLint companion under its own package name, from `packages/eslint-plugin-rhythmguard`. It re-exports `stylelint-plugin-rhythmguard/eslint`, so the rules, options and messages are one implementation; it exists so a search for an ESLint Tailwind plugin finds it. Published by the release run once the package has a trusted publisher.
+
+### Changed
+
+- The post-publish smoke waits up to ten minutes for the registry to list the new version before deciding it is unpublished. It checked once, and the registry took three minutes to list 3.7.1, so the smoke skipped itself and had to be dispatched by hand.
+
+## [3.7.1] - 2026-09-17
+
+### Fixed
+
+- Sass maps declared through a merge helper are read: `$spacers: defaults((...), $spacers)` (Bootstrap v6), `map.merge($base, (...))` and `map-merge((...), (...))` contribute the merged map, later keys winning. The reader also follows Sass assignment rules now: a later plain assignment replaces an earlier `!default`, a later `!default` does not. Before, the first assignment always won, so Bootstrap v6's `$spacers: () !default;` hid the map that followed it and `scale: "auto"` fell back. ([#143](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/143))
+
+### Changed
+
+- The quiet benchmark has a `bootstrap-v6` row, the branch its maintainers asked to see (twbs/bootstrap#42907); the manifest accepts a `ref` so a row can pin a branch other than the default.
+- The release verify matrix and the post-publish smoke are back on the self-hosted farm. The repository variable `RELEASE_ON_HOSTED=true` moves a release onto GitHub-hosted runners while the farm is down, without a workflow edit or a re-cut; the release checklist explains when to use it.
+
 ## [3.7.0] - 2026-09-17
 
 ### Added

package/CONTRIBUTING.md

@@ -106,7 +106,7 @@ The maintainer aims to respond to issues and PRs within a week. Small PRs merge
 
 ## Releases
 
-Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies the matrix and publishes through npm trusted publishing (OIDC), on GitHub-hosted runners so a release does not depend on the self-hosted farm. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
+Maintainer-run. Bump `package.json` and `CHANGELOG.md`, create a GitHub release, and `release.yml` verifies on the self-hosted matrix and publishes through npm trusted publishing (OIDC) from a GitHub-hosted job. The checklist covers cutting a release while the farm is down. Provenance is automatic. The checklist is in [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md).
 
 ## Benchmarking performance
 
@@ -116,3 +116,11 @@ npm run bench:perf:fix
 ```
 
 Compares runtime against `stylelint-scales` on a deterministic corpus. Method in [`docs/BENCHMARKING.md`](./docs/BENCHMARKING.md).
+
+## The README recording
+
+`assets/quickstart.gif` is recorded with [vhs](https://github.com/charmbracelet/vhs) from `assets/quickstart.tape` on a shallow clone of Bootstrap `v6-dev` at `/tmp/bootstrap`. Re-record when the quickstart output changes: `git clone --depth 1 --branch v6-dev https://github.com/twbs/bootstrap.git /tmp/bootstrap && vhs assets/quickstart.tape`, then bump the `?v=` cache key on the image in `README.md`.
+
+## The browser playground
+
+`docs/index.html` runs the real rules through `docs/playground/rhythmguard.js`, an esbuild bundle of `src/` with a Stylelint shim and no-op Node shims (`scripts/playground/`). Rebuild it after any change under `src/` that the rules use: `npm run build:playground`, and commit the file. `test/contracts/playground.test.js` rebuilds the bundle and fails when the committed one is stale, and checks that the page's sample gets the same warnings from the bundle and from Stylelint.

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=10" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=12" width="100%" alt="Rhythmguard: stable local evidence for design system drift" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -7,7 +7,7 @@
 Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=370)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=380)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
 
@@ -18,10 +18,16 @@ What it is not: it does not check colors or hex values, and the Stylelint rules
 ## Start here
 
 ```bash
-npx rhythmguard
+npx stylelint-plugin-rhythmguard
 ```
 
-No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. Then:
+No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. This is the whole run on Bootstrap's `v6-dev` branch, unedited:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/quickstart.gif?v=1" width="100%" alt="Terminal recording: npx stylelint-plugin-rhythmguard on Bootstrap v6-dev detects the stack, infers the 13-step spacing scale from scss/_config.scss, reports 20 off-scale values in CSS and prints a .stylelintrc.json to paste" />
+</p>
+
+Then:
 
 ```bash
 npm install --save-dev stylelint stylelint-plugin-rhythmguard
@@ -41,7 +47,7 @@ That enables `rhythmguard/use-scale` on spacing properties with the default 4px
 }
 ```
 
-For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion:
+For class strings in JSX, TSX, Vue, Svelte or Astro, add the ESLint companion. It is the same rules under two names: `stylelint-plugin-rhythmguard/eslint` if you already have this package, or [`eslint-plugin-rhythmguard`](packages/eslint-plugin-rhythmguard#readme) on its own.
 
 ```js
 // eslint.config.js
@@ -81,7 +87,7 @@ npx rhythmguard audit ./src --since-baseline --fail-on-new-drift
 npx rhythmguard audit ./src --format github
 ```
 
-The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md).
+The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md). In GitHub Actions, [`PetriLahdelma/rhythmguard-action@v1`](https://github.com/PetriLahdelma/rhythmguard-action) runs the audit, annotates the diff, comments on the pull request and fails on new drift in one step.
 
 `npx rhythmguard audit ./src --plan` turns the report into a proposed `decisions` section (adopt a value, allow it, or snap it), and `npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write` executes one decision as one reviewable change; see [decisions](docs/AUDIT.md#decisions). `npx rhythmguard init` writes a starter config for your stack, and `init --agents all` installs the coding-agent instructions. `npx rhythmguard doctor` checks the setup.
 
@@ -95,9 +101,10 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
 - [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block, installable with `npx rhythmguard init --agents all` for Claude Code, Cursor and Copilot
 - [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
+- [Agent evals](docs/AGENT_EVALS.md): does a finding get a coding agent to zero drift, in how many rounds, at what cost, against a rules-only control
 - [Architecture](docs/ARCHITECTURE.md): the layers, the rule kit, the invariants and where each is enforced
 - [Product direction](docs/STRATEGY_2026-09.md)
-- Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/), a simplified re-implementation for trying values in the browser; the real rules run under Node ([#57](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/57) tracks bundling them)
+- Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/) runs the real rules, bundled for the browser, on CSS or SCSS you paste; `scale: "auto"`, tokens and fixes included, and a test proves it reports what Stylelint reports
 
 ## Compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.7.0",
+  "version": "3.8.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"
@@ -62,6 +62,11 @@
       "require": "./src/audit/index.js",
       "import": "./src/audit/index.mjs"
     },
+    "./cli": {
+      "types": "./types/cli.d.ts",
+      "require": "./src/cli/index.js",
+      "import": "./src/cli/index.mjs"
+    },
     "./rules/use-scale": {
       "types": "./types/rule.d.ts",
       "require": "./src/rules/use-scale/index.js",
@@ -117,7 +122,9 @@
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "build:agents": "node scripts/build-agents.mjs",
     "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs",
-    "bench:outreach": "node scripts/bench/outreach.mjs"
+    "bench:outreach": "node scripts/bench/outreach.mjs",
+    "build:playground": "node scripts/build-playground.mjs",
+    "bench:agents": "node scripts/bench/agents/run.mjs"
   },
   "repository": {
     "type": "git",
@@ -151,9 +158,11 @@
     "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.126.0",
     "@eslint/js": "^9.39.5",
     "@types/node": "^22.20.1",
-    "c8": "^10.1.3",
+    "c8": "^12.0.0",
+    "esbuild": "^0.25.10",
     "eslint": "^9.39.5",
     "postcss-scss": "^4.0.9",
     "stylelint": "^16.15.0",

package/src/cli/index.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 'use strict';
 
-const command = process.argv[2];
-
 const HELP = `Usage: rhythmguard [command]
 
 With no command: zero-config quickstart. Detects your stack and tokens, infers
@@ -29,23 +27,34 @@ Examples:
   npx rhythmguard doctor
 `;
 
-if (command === '--help' || command === '-h') {
-  process.stdout.write(HELP);
-  process.exit(0);
+/** Dispatch on process.argv. The `rhythmguard` bin and the `rhythmguard` alias package both call this. */
+function main() {
+  const command = process.argv[2];
+
+  if (command === '--help' || command === '-h') {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+
+  if (!command || command === 'quickstart') {
+    require('./quickstart').run();
+  } else if (command === 'audit') {
+    require('./audit').run();
+  } else if (command === 'fix') {
+    require('./fix').run();
+  } else if (command === 'init') {
+    require('./init').run();
+  } else if (command === 'doctor') {
+    require('./doctor');
+  } else {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    process.stdout.write(HELP);
+    process.exit(1);
+  }
 }
 
-if (!command || command === 'quickstart') {
-  require('./quickstart').run();
-} else if (command === 'audit') {
-  require('./audit').run();
-} else if (command === 'fix') {
-  require('./fix').run();
-} else if (command === 'init') {
-  require('./init').run();
-} else if (command === 'doctor') {
-  require('./doctor');
-} else {
-  process.stderr.write(`Unknown command: ${command}\n\n`);
-  process.stdout.write(HELP);
-  process.exit(1);
+module.exports = { HELP, main };
+
+if (require.main === module) {
+  main();
 }

package/src/cli/index.mjs

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cli = require('./index.js');
+
+export default cli;
+export const HELP = cli.HELP;
+export const main = cli.main;

package/src/core/token-sources.js

@@ -413,6 +413,36 @@ function collectScssTokens(source, matchesKind) {
   return tokens;
 }
 
+/**
+ * A variable resolver over a Sass source text, for evaluating declaration
+ * values: same-file declarations first, then `fallback(name)` for a length
+ * declared elsewhere (a scaleSources file, an installed package).
+ */
+function createScssVariableResolver(source, fallback = () => null) {
+  const declarations = parseScssDeclarations(source || '');
+  const cache = new Map();
+  const resolveVariable = (name, stack) => {
+    if (cache.has(name)) {
+      return cache.get(name);
+    }
+    if (stack.has(name)) {
+      return null;
+    }
+    let value = null;
+    if (declarations.has(name)) {
+      stack.add(name);
+      const raw = declarations.get(name);
+      value = isScssMap(raw) ? null : evaluateScssExpression(raw, resolveVariable, stack);
+      stack.delete(name);
+    } else {
+      value = fallback(name);
+    }
+    cache.set(name, value);
+    return value;
+  };
+  return resolveVariable;
+}
+
 /** `$<namespace>-spacing-points`, `$<ns>-space-scale`: one namespace segment before the anchor. */
 const NAMESPACED_SPACING_MAP = /^\$[a-z0-9]+-(?:space|spacing|spacer)s?(?:-|$)/i;
 const MIN_NAMESPACED_MAP_LENGTHS = 4;
@@ -456,15 +486,67 @@ function parseScssDeclarations(source) {
     }
 
     startPattern.lastIndex = index;
+    const isDefault = /!default\b/.test(value);
     const cleaned = value.replace(/!(default|global)\b/g, '').trim();
-    if (cleaned && !declarations.has(name)) {
+    // Sass semantics at the top level: `!default` assigns only when the variable is
+    // still unset, a plain assignment always wins. Bootstrap v6 declares
+    // `$spacers: () !default;` and then `$spacers: defaults((...), $spacers);`.
+    if (cleaned && (!declarations.has(name) || !isDefault)) {
       declarations.set(name, cleaned);
     }
   }
 
+  for (const [name, raw] of declarations) {
+    const unwrapped = unwrapScssMapCall(raw, declarations);
+    if (unwrapped) {
+      declarations.set(name, unwrapped);
+    }
+  }
+
   return declarations;
 }
 
+/**
+ * A map declared through a merge helper, read as the map it produces:
+ * `defaults((...), $spacers)` (Bootstrap v6), `map.merge($a, (...))`,
+ * `map-merge((...), (...))`. Map-literal arguments and variables that hold a
+ * map are merged left to right with later keys winning, as Sass does; anything
+ * else (an unset `!default` placeholder, an expression) contributes nothing.
+ */
+const SCSS_MAP_MERGE_CALL = /^(?:defaults|map\.merge|map-merge)\s*\(([\s\S]*)\)$/;
+
+function unwrapScssMapCall(raw, declarations) {
+  const match = raw.match(SCSS_MAP_MERGE_CALL);
+  if (!match) {
+    return null;
+  }
+  const entries = new Map();
+  for (const argument of splitTopLevel(match[1], ',')) {
+    const text = argument.trim();
+    let mapLiteral = null;
+    if (isScssMap(text)) {
+      mapLiteral = text;
+    } else if (/^\$[\w-]+$/.test(text)) {
+      const referenced = declarations.get(text.slice(1));
+      if (referenced && isScssMap(referenced)) {
+        mapLiteral = referenced;
+      }
+    }
+    if (!mapLiteral) {
+      continue;
+    }
+    for (const entry of splitTopLevel(mapLiteral.slice(1, -1), ',')) {
+      const pair = splitTopLevel(entry, ':');
+      if (pair.length < 2) continue;
+      entries.set(pair[0].trim(), pair.slice(1).join(':').trim());
+    }
+  }
+  if (entries.size === 0) {
+    return null;
+  }
+  return `(${[...entries].map(([key, expression]) => `${key}: ${expression}`).join(', ')})`;
+}
+
 function isScssMap(raw) {
   return raw.startsWith('(') && raw.endsWith(')') && /:/.test(raw);
 }
@@ -535,20 +617,19 @@ function tokenizeScssExpression(expression) {
       }
       return null;
     }
+    const start = index + (match[0].length - match[0].trimStart().length);
     index = SCSS_TOKEN_PATTERN.lastIndex;
-    if (match[1] !== undefined) tokens.push({ type: 'number', raw: match[1] });
-    else if (match[2] !== undefined) tokens.push({ type: 'var', name: match[2].slice(1) });
-    else if (match[3] !== undefined) tokens.push({ type: 'call', name: match[3] });
-    else tokens.push({ type: 'op', value: match[4] });
+    const span = { end: index, start };
+    if (match[1] !== undefined) tokens.push({ type: 'number', raw: match[1], ...span });
+    else if (match[2] !== undefined) tokens.push({ type: 'var', name: match[2].slice(1), ...span });
+    else if (match[3] !== undefined) tokens.push({ type: 'call', name: match[3], ...span });
+    else tokens.push({ type: 'op', value: match[4], ...span });
   }
   return tokens;
 }
 
-function evaluateScssExpression(expression, resolveVariable, stack) {
-  const tokens = tokenizeScssExpression(expression.trim());
-  if (!tokens || tokens.length === 0) {
-    return null;
-  }
+/** A recursive-descent parser over Sass expression tokens; `parseExpression` consumes one arithmetic expression. */
+function createScssParser(tokens, resolveVariable, stack) {
   let position = 0;
   const peek = () => tokens[position];
   const next = () => tokens[position++];
@@ -635,8 +716,46 @@ function evaluateScssExpression(expression, resolveVariable, stack) {
     return value;
   };
 
-  const result = parseExpression();
-  return position === tokens.length ? result : null;
+  return {
+    get position() { return position; },
+    parseExpression,
+  };
+}
+
+function evaluateScssExpression(expression, resolveVariable, stack) {
+  const tokens = tokenizeScssExpression(expression.trim());
+  if (!tokens || tokens.length === 0) {
+    return null;
+  }
+  const parser = createScssParser(tokens, resolveVariable, stack);
+  const result = parser.parseExpression();
+  return parser.position === tokens.length ? result : null;
+}
+
+/**
+ * A space-separated Sass value (`$spacer * .3 $spacer`) as its evaluated terms,
+ * each with the source text it came from, or null when any term cannot be
+ * evaluated (an unknown variable, a keyword, a function the evaluator does not
+ * know). A `-` between terms is read as subtraction, as Sass does.
+ */
+function evaluateScssValueList(value, resolveVariable, stack) {
+  const tokens = tokenizeScssExpression(value);
+  if (!tokens || tokens.length === 0) {
+    return null;
+  }
+  const parser = createScssParser(tokens, resolveVariable, stack);
+  const terms = [];
+  while (parser.position < tokens.length) {
+    const startToken = tokens[parser.position];
+    const before = parser.position;
+    const result = parser.parseExpression();
+    if (!result || parser.position === before) {
+      return null;
+    }
+    const endToken = tokens[parser.position - 1];
+    terms.push({ ...result, end: endToken.end, start: startToken.start, text: value.slice(startToken.start, endToken.end) });
+  }
+  return terms;
 }
 
 function formatScssValue(value) {
@@ -853,6 +972,8 @@ function formatPath(filePath) {
 }
 
 module.exports = {
+  createScssVariableResolver,
+  evaluateScssValueList,
   VALID_TOKEN_KINDS,
   VALID_TOKEN_SOURCE_FORMATS,
   addDefinition,

package/src/rules/use-scale/index.js

@@ -29,6 +29,7 @@ const {
   collectTokenDefinitions,
   withResolvedScale,
 } = require('../../core/scale-inference');
+const { createScssVariableResolver, evaluateScssValueList } = require('../../core/token-sources');
 
 const { createTokenRegex, reportInvalidPreset, reportProblem, reportValueNode } = require('../report');
 const { decisionFor, loadRcDecisions } = require('../../core/decisions');
@@ -59,13 +60,17 @@ function readDecisions(options, { result, root }) {
 
 function checkLengthValue({
   decl,
+  evaluated = null,
+  fixable = true,
   node,
   options,
   report,
   scaleByUnit,
   scalePx,
 }) {
-  const parsedLength = parseLengthToken(node.value);
+  // `evaluated` is a length that came from a Sass expression; the node's text is
+  // the expression, which is reported but never rewritten.
+  const parsedLength = evaluated || parseLengthToken(node.value);
 
   if (!parsedLength) {
     return false;
@@ -130,11 +135,11 @@ function checkLengthValue({
       return false;
     }
 
-    const fixedValue = options.fixToScale
+    const fixedValue = options.fixToScale && fixable
       ? replacementFor(parsedLength, nearest.nearest, options)
       : null;
 
-    report(node.value, decl, node, nearest, fixedValue, unit);
+    report(node.value, decl, node, nearest, fixedValue, unit, evaluated ? evaluatedNote(evaluated, options) : '');
     return true;
   }
 
@@ -154,11 +159,58 @@ function checkLengthValue({
     return false;
   }
 
-  const fixedValue = options.fixToScale
+  const fixedValue = options.fixToScale && fixable
     ? replacementFor(parsedLength, nearest.nearest, options)
     : null;
 
-  report(node.value, decl, node, nearest, fixedValue, 'px');
+  report(node.value, decl, node, nearest, fixedValue, 'px', evaluated ? evaluatedNote(evaluated, options) : '');
+  return true;
+}
+
+/** What a Sass expression came to, so the reader sees the number the scale was checked against. */
+function evaluatedNote(evaluated, options) {
+  const px = toPx(evaluated.number, evaluated.unit, options.baseFontSize);
+  return px === null ? '' : `Evaluates to ${formatLength(px, 'px')}.`;
+}
+
+/**
+ * Sass values (`$spacer * .3`, `math.div($spacer, 2)`, `$y $x`) are evaluated
+ * with the file's own variables first and the project's spacing tokens second,
+ * and each term is checked like a literal. Terms that do not resolve are left
+ * alone, as they always were.
+ */
+function checkSassValue({ decl, options, report, resolveVariable, scaleByUnit, scalePx }) {
+  const terms = evaluateScssValueList(decl.value, resolveVariable, new Set());
+  if (!terms) {
+    // Not fully evaluable (an unknown variable, interpolation, a keyword): the
+    // literal walk below still checks the plain lengths in the value.
+    return false;
+  }
+  // Right to left, so a fix spliced into an earlier term never shifts the spans
+  // of the terms still to be checked. Stylelint orders the warnings by position.
+  for (const term of [...terms].reverse()) {
+    if (!term.unit || term.number === 0) {
+      continue;
+    }
+    const node = {
+      sourceIndex: term.start,
+      type: 'word',
+      get value() { return term.text; },
+      // The fix writes into the declaration at the term's span.
+      set value(replacement) { decl.value = `${decl.value.slice(0, term.start)}${replacement}${decl.value.slice(term.end)}`; },
+    };
+    checkLengthValue({
+      decl,
+      evaluated: { number: term.number, unit: term.unit },
+      // A term that is a plain literal keeps its autofix; an expression is only reported.
+      fixable: parseLengthToken(term.text) !== null,
+      node,
+      options,
+      report,
+      scaleByUnit,
+      scalePx,
+    });
+  }
   return true;
 }
 
@@ -195,13 +247,13 @@ const ruleFunction = (primary, secondaryOptions) => {
     let fallbackNote = autoScaleFallbackNote(options.scaleInference);
     const getScaleStateForProperty = createPropertyScaleResolver(options);
 
-    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px') => {
+    const report = (value, decl, node, nearest, fixedValue = null, nearestUnit = 'px', extraNote = '') => {
       const lower = nearest ? formatLength(nearest.lower, nearestUnit) : 'n/a';
       const upper = nearest ? formatLength(nearest.upper, nearestUnit) : 'n/a';
       const tokenNote = nearest ? tokenHoldsNote(fixedValue, formatLength(nearest.nearest, nearestUnit)) : '';
       reportValueNode({
         decl,
-        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, options.note].filter(Boolean).join(' ')),
+        message: messages.rejected(value, lower, upper, [fallbackNote, tokenNote, extraNote, options.note].filter(Boolean).join(' ')),
         node,
         replacement: fixedValue,
         result,
@@ -210,9 +262,24 @@ const ruleFunction = (primary, secondaryOptions) => {
       fallbackNote = '';
     };
 
+    // Built on the first Sass value seen, so plain CSS pays nothing.
+    let resolveSassVariable = null;
+    const sassResolver = () => {
+      if (!resolveSassVariable) {
+        const definitions = collectTokenDefinitions({ baseFontSize: options.baseFontSize, root, scaleSources: options.scaleSources, tokenRegex });
+        resolveSassVariable = createScssVariableResolver(root.source && root.source.input ? root.source.input.css : '', (name) => {
+          const definition = definitions.get(`$${name}`);
+          const first = definition ? [...definition.values][0] : null;
+          const parsed = first ? parseLengthToken(String(first).trim()) : null;
+          return parsed && parsed.unit ? { number: parsed.number, unit: parsed.unit } : null;
+        });
+      }
+      return resolveSassVariable;
+    };
+
     root.walkDecls((decl) => {
       const prop = decl.prop.toLowerCase();
-      if (prop.startsWith('--')) {
+      if (prop.startsWith('--') || prop.startsWith('$')) {
         return;
       }
 
@@ -221,6 +288,11 @@ const ruleFunction = (primary, secondaryOptions) => {
       }
 
       const { scaleByUnit, scalePx } = getScaleStateForProperty(prop);
+
+      if (decl.value.includes('$') && checkSassValue({ decl, options, report, resolveVariable: sassResolver(), scaleByUnit, scalePx })) {
+        return;
+      }
+
       const parsed = valueParser(decl.value);
       let changed = false;
 

package/types/cli.d.ts

@@ -0,0 +1,9 @@
+/** The usage text printed by `rhythmguard --help`. */
+export const HELP: string;
+
+/** Run the rhythmguard CLI against `process.argv`. Exits the process on completion or error. */
+export function main(): void;
+
+declare const cli: { HELP: string; main: typeof main };
+
+export default cli;