stylelint-plugin-rhythmguard 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -6,6 +6,46 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.13.0] - 2026-10-18
+
+### Fixed
+
+- `checkMathBounds` checks bounds inside translations. `use-scale`, `prefer-token` and `no-offscale-transform` skipped it for `transform`, so `transform: translateX(clamp(13px, 2vw, 17px))` gave no finding while `padding: clamp(13px, 2vw, 17px)` reported both bounds; `no-offscale-transform` accepted the option but ignored it everywhere, the `translate` properties included. The `clamp()` minimum and maximum and the length arguments of `min()` and `max()` are now checked, named and fixed in translate functions and in `translate`, `translate-x`, `translate-y` and `translate-z` as anywhere else. Only configs that set `checkMathBounds: true` see new reports. ([#272](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/272))
+- Option shapes that turned a rule into a silent no-op are invalid options now. `scale: ["auto"]`, an empty `scale` or `customScale`, an empty list or an unknown preset in `scales` or `propertyScales` (`{ spacing: [] }`, `{ padding: { preset: "nope" } }`), and `use-motion-scale`'s `durationScale: 100`, `durationScale: []` or `durationUnits: "s"` were accepted and then checked nothing or fell back to the defaults; each is now an invalid option warning, which fails the Stylelint run as a misspelled option does. `"auto"` stays valid as the whole `scale`. A preset name as a `propertyScales` value (`{ padding: "rhythmic-8" }`), typed `scaleOrPreset` in the docs, was rejected and is accepted now. `audit.scales` in `.rhythmguardrc.json` uses the same check, so an empty list or unknown preset there is refused with `scales must map ...`. ([#273](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/273))
+- `use-scale` and `no-offscale-transform` say why a negative value or a percentage is reported. With `allowNegative: false` or `allowPercentages: false` the message read `Use scale values (nearest: n/a).`, although `-8px` is on the scale. It now reads `Negative values are disabled for this rule.` or `Percentages are disabled for this rule.`, as `tailwind-class-use-scale` already does; see Messages. What is reported is unchanged. ([#274](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/274))
+- `prefer-token` finds a px `tokenMap` key for a converted length. The key was built from the raw conversion, so `padding: 1.1rem` at `baseFontSize: 14` looked up `15.400000000000002px`, missed `"15.4px": "var(--space-x)"` and read `No known token holds this value`. The key is now formatted like every other length, so the value reads `Use var(--space-x).` and is fixed to it. This changes the message and adds a fix for such values. ([#275](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/275))
+- The `use-motion-scale` docs print the rule's messages. They showed `Use motion scale values` and `Use an easing token.`, while the rule reports `Use duration scale values (nearest: 150ms or 200ms).` and `Use motion tokens for easing decisions.`; the docs now match, and a test lints the documented example against them. The messages are unchanged. ([#276](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/276))
+- A file saved with a UTF-8 byte order mark is read like one without. A JSON token source with a BOM failed with `Unable to parse token source ...: Unexpected token`, a `.rhythmguardrc.json` with one was ignored by the lint (`.rhythmguardrc.json could not be read`) and stopped the audit with `Invalid Rhythmguard config`, and a baseline with one stopped `--since-baseline`. A leading BOM is now stripped before parsing token sources (JSON and CSS), `.rhythmguardrc.json` in the lint, the audit and `rhythmguard doctor`, `tokenMapFile`, and baselines. ([#291](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/291))
+- A bare `--space` is a spacing base only when the other spacing tokens do not form a scale on their own. `:root { --space: 1rem; --space-s: .5rem; --space-m: 1rem; --space-l: 2rem; --space-xl: 3rem }` with `scale: "auto"` gave multiples of 16px up to 1536px, so 40px and 56px passed while 12px was reported against 16px steps; that ladder is now the scale and `--space` one step on it. A project that declares `--space: 0.25rem` and writes each step as `calc(var(--space) * N)`, as Discourse does, keeps the multiples, since its steps are not plain lengths. `--spacing` (Tailwind v4) is always a base. ([#293](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/293))
+- Audit token ladders compare a ladder of negative steps by magnitude. `--space-negative-1: -4px` to `--space-negative-3: -16px` was reported as two `inverted` problems; a ladder whose every step is negative is now compared by magnitude, and a ladder that crosses zero keeps its signed order. ([#294](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/294))
+- Audit token chains no longer count shadow tokens as spacing tokens. `inset` in Tailwind v4's `--inset-shadow-*` made them spacing-named, so a Tailwind `theme.css` added three `non-length` chains and read "1 of 4 spacing tokens resolve". Names containing `shadow` are now left out of the chains. ([#295](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/295))
+- An explicit `tokenPattern` now selects the tokens `scale: "auto"` reads from token files, as it already did for `fixWith: "token"`. With `{ scale: "auto", tokenPattern: "^--size-", scaleSources: ["sizes.css"] }` and `--size-1` to `--size-4` in that file, inference found nothing and fell back to `rhythmic-4`, while fixes wrote the `--size-*` tokens. The pattern is now applied to `scaleSources`, `.rhythmguardrc.json` token sources and installed token packages on top of the spacing names, unless a source sets its own `tokenPattern`, so inference and fixes read the same tokens. This changes the inferred scale for configs that set both `scale: "auto"` and `tokenPattern` when a token file has tokens the pattern matches but the spacing names do not. ([#296](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/296))
+- The docs list the `scale: "auto"` sources in the order the code reads them: `tailwindConfigPath` comes before installed token packages. `docs/rules/use-scale.md` and `docs/FOR_CONFIG_AUTHORS.md` had them the other way round. The order itself is unchanged. ([#297](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/297))
+- `tailwind-class-use-scale` keeps the sign of a double negative. In `-m-[-13px]` the two signs cancel and Tailwind writes `margin: 13px`, but the rule treated either sign as making the value negative, so the fix wrote `-m-3` (-12px) and the message named `-m-3` or `-m-4`. The value is now negative only when exactly one of the two signs is there, so `-m-[-13px]` becomes `m-3`; with `spacingUnit: false` it still becomes `-m-[-12px]`, and with `allowNegative: false` a double negative is checked like any positive value instead of being reported as negative. The audit's class-string findings change the same way. ([#277](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/277))
+- `eslint --fix-type` applies the Rhythmguard fixes. Neither ESLint rule declared `meta.type`, and ESLint skips the fixes of a rule without one whenever `--fix-type` is given, so `--fix-type problem,suggestion,layout` fixed nothing. Both rules are now `type: "suggestion"`. ([#278](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/278))
+- The ESLint `configs.recommended` works as a flat config of its own. It had only `rules`, so `export default [rhythmguard.configs.recommended]` failed with `could not find plugin "rhythmguard-tailwind"`. It now also has `plugins: { "rhythmguard-tailwind": plugin }`; spreading `configs.recommended.rules` into a block that registers the plugin works as before. ([#279](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/279))
+- The Stylelint option types accept the package's own configs. `RhythmguardRuleOptions` lacked most options, so typing the shipped `embed` config failed on `severity` and `motion` on `durationScale`. The types now have every option each rule accepts, as `RhythmguardUseScaleOptions`, `RhythmguardPreferTokenOptions`, `RhythmguardTransformRuleOptions` and `RhythmguardMotionRuleOptions` (with `RhythmguardRuleOptions` covering all three length rules), Stylelint's own `severity`, `message`, `disableFix`, `reportDisables` and `url`, and the `[true]` form. `rules` in `RhythmguardStylelintConfig` types each Rhythmguard rule with its own options. `includeMathFunctions`, which no rule accepts, is gone from the types; use `enforceInsideMathFunctions`. Every shipped config now declares its type and is checked by `npm run typecheck`. ([#280](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/280))
+- Smaller type and playground mismatches. `getScalePreset` and `getCommunityScaleMetadata` are typed as returning `null` for an unknown name, which is what they return. The subpath types (`stylelint-plugin-rhythmguard/eslint`, `/audit`, `/presets`, `/configs/*`, `/rules/*`, `/cli`) resolve under `moduleResolution: "node"` through `typesVersions`, and `eslint-plugin-rhythmguard`'s types import the package root, so they no longer fail with `TS2307`. The playground's `tailwind` config includes the `strict` config it extends, so it runs `use-scale` and `no-offscale-transform` as Stylelint does, not only `prefer-token`. ([#281](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/281))
+- The audit API types match the report. `AuditSummary` declared `cleanliness`, `filesWithFindings` and `findingCount`, `AuditFinding` declared `message`, `AuditBaselineComparison` declared `resolvedFindings`, and `config` was typed as a string; the report has `scaleCleanliness`, `filesWithIssues`, `totalFindings`, `text`, `resolvedFindingsCount` and `config: { file }`. The types now describe the report as `createAuditReport` returns it, `AuditOptions` marks `format`, `outputPath`, `maxFindings`, `minCleanliness`, `failOnNewDrift` and `badgeMetric` as CLI only (`createAuditReport` never read them), and `loadAuditConfig` has its real return type. `createAuditReport({ scale: undefined })` used the undefined over the default scale and inferred one from the scanned CSS; a key set to `undefined` now counts as omitted, so the default or the config file value applies. ([#284](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/284))
+- Numeric audit flags refuse empty, whitespace and non-decimal values. `--min-cleanliness=` (an unset `$THRESHOLD` in CI) gated at 0% and passed, `--max-findings=` became 0, and `--max-findings 0x10` became 16, because each value went through `Number()`. `--max-findings`, `--min-cleanliness`, `--token-candidate-min-count` and `--base-font-size` (also on `rhythmguard fix`) now take plain decimal digits only, with a fraction where one makes sense, and exit 1 with their existing message otherwise. In `.rhythmguardrc.json` a JSON number or a decimal string is accepted as before; `null` and `true`, which read as 0 and 1, are refused. ([#282](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/282))
+- `audit.scales` reaches `--plan` and the reported scale. With `{"scales":{"spacing":[0,5,10],"typography":[12,14,16]}}`, `--plan` proposed `margin: 8px` with `"nearest": ["8px","8px"]` and `font-size: 15px` with `["12px","16px"]`, taken from the project scale, and `contracts.scale.values` still read `0, 4, 8, ..., 32`. A `spacing` list or preset is now the audit's spacing scale (`source: "explicit"`), as it already was for `use-scale`; `--plan` takes each value's nearest steps from the scale it was checked against, gives a value found in groups with different scales one entry per scale, and leaves `nearest` empty for a group set to `"auto"`. Token opportunities, Tailwind class strings and token chains now read the `spacing` entry too, so this changes findings for configs that set `audit.scales.spacing`. ([#283](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/283))
+- Markdown reports keep their tables and code spans intact. A scale source file named `a|b.css` split the `Scale source` row, and a file named ``we`ird.css`` broke out of its code span, since a backslash escapes nothing inside a code span. The scale source row is escaped now, and code spans use a fence one backtick longer than any run in the value; token names, chain terminals, ladder steps and the directory line get the same treatment. ([#285](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/285))
+- `init --help`, `doctor --help` and `quickstart --help` print their usage. `echo y | rhythmguard init --help` wrote `.stylelintrc.json`, doctor ran its checks, quickstart audited, and a typo such as `init --agnets claude` fell through to the interactive init. Every command now handles `--help` and `-h` and refuses an option it does not know before doing anything; `init --agents` with no value still means `all`. ([#286](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/286))
+- The audit commands quickstart suggests reproduce its result. Quickstart audits with `--scale auto` and the token files it finds, but suggested `npx rhythmguard audit . --format markdown`, which used the default scale: with a `tokens.json` scale of `0, 4, 8, 12, 20`, quickstart reported `16px` and the suggested audit and baseline reported `20px`. The suggested commands now carry the same flags, for example `npx rhythmguard audit . --scale auto --token-source ./tokens.json --format markdown`. ([#287](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/287))
+- `rhythmguard fix` checks its target and reports where each literal is. `fix ./nope` and `fix ./a.css` ended in a raw `binding.readdir` stack trace; they now exit 1 with the audit's `Directory not found: ./nope` and `Not a directory: ./a.css`. A literal in a value that spans lines was listed at the declaration's line with a column past its end (`2:24` for a `10px` on line 4); positions are now counted through the value. ([#288](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/288))
+- The audit follows symbolic links. A linked directory or stylesheet was skipped without a word (`cssFiles: 1` and no findings for `src/linked -> ../real` and `src/l.css -> ../real/r.css`), in a full run and with `--staged`. Links that resolve inside the audited directory are now followed, a link back up the tree is not walked twice, and a file reached by more than one path is scanned once, under its own path when the walk reaches it directly. Security: a link that resolves outside the directory (`../../other-project`, `/etc`) is never followed, in a full run, with `--staged` and with `--since`, and is counted as `Links not followed` in text and Markdown output (`scanned.linksOutsideRoot` in the report); `rhythmguard fix` walks the same way and never writes through a symbolic link, so `fix --write` cannot rewrite a file outside the directory it was given. This adds findings for projects that link stylesheets into the audited directory. ([#289](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/289))
+- A corrupt baseline names its file. `--since-baseline` with an invalid `.rhythmguard-baseline.json` failed with `Expected property name or '}' in JSON at position 1` alone; the error now reads `Invalid baseline file .rhythmguard-baseline.json: <the JSON error>`, also when a `--staged` or `--since` run merges into it. ([#290](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/290))
+
+### Messages
+
+- `use-scale`: with `allowNegative: false` a negative value reads `Unexpected value "-8px". Negative values are disabled for this rule.`, and with `allowPercentages: false` a percentage reads `Unexpected value "5%". Percentages are disabled for this rule.`, where both read `Unexpected off-scale value "...". Use scale values (nearest: n/a).` A `clamp()`, `min()` or `max()` bound names its position: `Unexpected clamp() minimum "-8px". Negative values are disabled for this rule.` ([#274](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/274))
+- `no-offscale-transform`: the same cases read `Unexpected transform translation value "-8px". Negative values are disabled for this rule.` and `Unexpected transform translation value "13%". Percentages are disabled for this rule.` instead of `Use scale values (nearest: n/a).` A bound checked by `checkMathBounds` names its position, as in `use-scale`: `Unexpected transform translation clamp() minimum "13px". Use scale values (nearest: 12px or 16px).`, with the px value after a rem or em bound. ([#274](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/274), [#272](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/272))
+- Audit: a baseline that is not valid JSON reads `Invalid baseline file <path>: <the JSON error>`. ([#290](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/290))
+- `rhythmguard init`, `doctor` and `quickstart`: `--help` prints `Usage: rhythmguard init [options]`, `Usage: rhythmguard doctor` or `Usage: rhythmguard [quickstart]` with the options; an unknown option reads `Unknown option: <option>` followed by the usage, and `init --agents=` reads `Missing value for --agents.` ([#286](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/286))
+- `rhythmguard fix`: a missing target reads `Directory not found: <path>` and a file `Not a directory: <path>`, as in the audit. ([#288](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/288))
+- Audit: text output adds `Links not followed  <n>  (they point outside the scanned directory)` and Markdown `| Symbolic links not followed (they point outside the scanned directory) | <n> |` when a symbolic link resolves outside the scanned directory. `rhythmguard fix` lists `skipped <file>: symbolic link to a path outside the directory; not followed` and `skipped <file>: reached through a symbolic link; rewrite the file it points to instead`. ([#289](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/289))
+- Quickstart: the `Next` section puts each note on its own line above its command (`PR-ready report:` then `npx rhythmguard audit . --scale auto ... --format markdown`), and the baseline note reads `Then gate only new drift in CI, with the same flags:`. ([#287](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/287))
+
 ## [3.12.0] - 2026-10-18
 
 ### Fixed

package/README.md

@@ -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=3120)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
+[![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3130)](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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.12.0",
+  "version": "3.13.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"
@@ -21,6 +21,28 @@
   "type": "commonjs",
   "main": "src/index.js",
   "types": "./types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "audit": [
+        "./types/audit.d.ts"
+      ],
+      "cli": [
+        "./types/cli.d.ts"
+      ],
+      "configs/*": [
+        "./types/config.d.ts"
+      ],
+      "eslint": [
+        "./types/eslint.d.ts"
+      ],
+      "presets": [
+        "./types/presets.d.ts"
+      ],
+      "rules/*": [
+        "./types/rule.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./types/index.d.ts",

package/src/audit/args.js

@@ -164,8 +164,27 @@ function parsePathOption(raw, optionName) {
   return String(raw);
 }
 
+/**
+ * A number typed on the command line or written in .rhythmguardrc.json. A
+ * JSON number is taken as is; a string must be plain decimal digits, with a
+ * fraction only where one is allowed. `Number()` alone would read an empty
+ * value (an unset `$THRESHOLD` in CI) as 0 and `0x10` as 16 (#282).
+ */
+const DECIMAL_INTEGER = /^\d+$/;
+const DECIMAL_NUMBER = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
+
+function parseDecimal(raw, pattern) {
+  if (typeof raw === 'number') {
+    return raw;
+  }
+  if (typeof raw === 'string' && pattern.test(raw)) {
+    return Number(raw);
+  }
+  return Number.NaN;
+}
+
 function parseNonNegativeInteger(raw, optionName) {
-  const value = Number(raw);
+  const value = parseDecimal(raw, DECIMAL_INTEGER);
   if (!Number.isInteger(value) || value < 0) {
     throw new Error(`${optionName} must be a non-negative integer.`);
   }
@@ -174,7 +193,7 @@ function parseNonNegativeInteger(raw, optionName) {
 }
 
 function parsePositiveInteger(raw, optionName) {
-  const value = Number(raw);
+  const value = parseDecimal(raw, DECIMAL_INTEGER);
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`${optionName} must be a positive integer.`);
   }
@@ -183,7 +202,7 @@ function parsePositiveInteger(raw, optionName) {
 }
 
 function parsePercentage(raw, optionName) {
-  const value = Number(raw);
+  const value = parseDecimal(raw, DECIMAL_NUMBER);
   if (!Number.isFinite(value) || value < 0 || value > 100) {
     throw new Error(`${optionName} must be a number between 0 and 100.`);
   }
@@ -267,7 +286,7 @@ function validateScale(scale, optionName = '--scale', raw = scale) {
 }
 
 function parseBaseFontSize(raw) {
-  const value = Number(raw);
+  const value = parseDecimal(raw, DECIMAL_NUMBER);
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error('--base-font-size must be a positive number.');
   }

package/src/audit/baseline.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { readJsonFile } = require('../core/json');
 const { exactScaleCleanliness } = require('./contract');
 const { findGitTopLevel } = require('./scan/files');
 const { formatPath } = require('./shared');
@@ -79,7 +80,7 @@ function applyBaselineComparison(report, baselinePath, scopeInput) {
     throw new Error(`Baseline file not found: ${baselinePath}`);
   }
 
-  const baseline = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+  const baseline = readBaselineFile(resolvedPath, baselinePath);
   const baselineFindings = Array.isArray(baseline.findings) ? baseline.findings : [];
   const scope = createBaselineScope(report, scopeInput);
   const currentFindings = getAllFindings(report);
@@ -113,6 +114,18 @@ function applyBaselineComparison(report, baselinePath, scopeInput) {
   report.summary.resolvedFindings = resolvedFindings.length;
 }
 
+/**
+ * A baseline file as JSON. A parse error names the file, so a corrupt
+ * baseline is not reported as a bare `JSON.parse` message (#290).
+ */
+function readBaselineFile(resolvedPath, baselinePath) {
+  try {
+    return readJsonFile(resolvedPath);
+  } catch (err) {
+    throw new Error(`Invalid baseline file ${baselinePath}: ${err.message}`, { cause: err });
+  }
+}
+
 function writeBaseline(report, baselinePath, scopeInput) {
   const resolvedPath = path.resolve(process.cwd(), baselinePath);
   const scope = createBaselineScope(report, scopeInput);
@@ -125,7 +138,7 @@ function writeBaseline(report, baselinePath, scopeInput) {
   // entries for the files it audited and keeps every other entry, so a scoped
   // run never shrinks the baseline.
   if (scope.scoped && fs.existsSync(resolvedPath)) {
-    const existing = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+    const existing = readBaselineFile(resolvedPath, baselinePath);
     if (!isContentKeyed(existing)) {
       throw new Error(`Cannot update ${baselinePath} from a --staged or --since run: it was written with formatVersion 1, keyed by line. Run --write-baseline once without --staged or --since to upgrade it.`);
     }

package/src/audit/codemod.js

@@ -9,7 +9,7 @@ const { numbersEqual, parseLengthToken, toPx } = require('../core/length');
 const { negateReplacement } = require('../core/token-index');
 const { isTokenFunction, propertyMatches, walkRootValueNodes } = require('../core/value-nodes');
 const { formatPath } = require('./shared');
-const { isCssFile, isScssFile, walkFiles } = require('./scan/files');
+const { isCssFile, isPathInside, isScssFile, isTemplateFile, walkFiles } = require('./scan/files');
 const { resolveScssSyntax } = require('./scan/stylesheets');
 
 /**
@@ -64,10 +64,11 @@ function replaceLength(root, { baseFontSize = 16, properties = null, px, replace
         return false;
       }
       const to = length.number < 0 ? negateReplacement(match.replacement) : match.replacement;
+      const position = positionInDeclaration(decl, declarationValueOffset(decl) + node.sourceIndex);
       changes.push({
-        column: (decl.source && decl.source.start ? decl.source.start.column : 1) + declarationValueOffset(decl) + node.sourceIndex,
+        column: position.column,
         from: node.value,
-        line: decl.source && decl.source.start ? decl.source.start.line : 1,
+        line: position.line,
         property: decl.prop,
         to,
       });
@@ -89,6 +90,22 @@ function declarationValueOffset(decl) {
   return decl.prop.length + between.length;
 }
 
+/**
+ * The line and column of `index`, an offset into the declaration as written
+ * (property, separator, value), counted from where the declaration starts. A
+ * value that spans lines puts later literals on later lines (#288).
+ */
+function positionInDeclaration(decl, index) {
+  const start = decl.source && decl.source.start ? decl.source.start : { column: 1, line: 1 };
+  const raws = decl.raws || {};
+  const text = `${decl.prop}${typeof raws.between === 'string' ? raws.between : ': '}${decl.value}`.slice(0, index);
+  const lastBreak = text.lastIndexOf('\n');
+  const breaks = text.split('\n').length - 1;
+  return breaks === 0
+    ? { column: start.column + index, line: start.line }
+    : { column: index - lastBreak, line: start.line + breaks };
+}
+
 /**
  * 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`
@@ -119,10 +136,26 @@ function parseStylesheet(filePath, source) {
  */
 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 walked = walkFiles(rootDir, ignorePatterns);
+  const files = walked.cssFiles.filter(isCssFile).sort();
   const results = [];
-  const skipped = [];
+  const skipped = walked.linksOutsideRoot
+    .filter((link) => !isTemplateFile(link))
+    .map((link) => ({ file: formatPath(path.join(rootDir, link)), reason: 'symbolic link to a path outside the directory; not followed' }));
+  const realRoot = fs.realpathSync(rootDir);
+  const rewritten = new Set();
   for (const filePath of files) {
+    // Never write through a symbolic link: a file is rewritten only at its own
+    // path inside the directory, and only once (#289).
+    const realPath = writableRealPath(filePath, rootDir, realRoot);
+    if (!realPath) {
+      skipped.push({ file: formatPath(filePath), reason: 'reached through a symbolic link; rewrite the file it points to instead' });
+      continue;
+    }
+    if (rewritten.has(realPath)) {
+      continue;
+    }
+    rewritten.add(realPath);
     const source = fs.readFileSync(filePath, 'utf8');
     let parsed;
     try {
@@ -148,6 +181,24 @@ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties =
   return { results, skipped };
 }
 
+/**
+ * The real path of `filePath` when it is the file's own path: no symbolic link
+ * between `rootDir` and the file, and the file inside `rootDir`. Null otherwise.
+ */
+function writableRealPath(filePath, rootDir, realRoot) {
+  let realPath;
+  try {
+    if (fs.lstatSync(filePath).isSymbolicLink()) {
+      return null;
+    }
+    realPath = fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+  const expected = path.join(realRoot, path.relative(rootDir, filePath));
+  return realPath === expected && isPathInside(realRoot, realPath) ? realPath : null;
+}
+
 module.exports = {
   replaceLength,
   runCodemod,

package/src/audit/config.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { normalizeDecisions } = require('../core/decisions');
+const { readJsonFile } = require('../core/json');
 const { SCALED_GROUPS, isGroupScalesMap } = require('../core/options');
 const { normalizeTokenKind } = require('../core/token-sources');
 const { normalizeTokenSourceEntry } = require('../core/token-source-entries');
@@ -43,7 +44,7 @@ function loadAuditConfig(parsed) {
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(resolvedPath, 'utf8'));
+    config = readJsonFile(resolvedPath);
   } catch (err) {
     throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: ${err.message}`, { cause: err });
   }

package/src/audit/contract.js

@@ -232,6 +232,7 @@ function buildReport({
   dir,
   externalTokenDefinitions,
   includeMotion,
+  linksOutsideRoot = [],
   motionFindings,
   parseErrorFindings = [],
   readSource,
@@ -323,6 +324,8 @@ function buildReport({
       stylelintIgnored,
       templateFiles: templateFiles.length,
       totalFiles,
+      // Symbolic links that resolve outside the scanned directory: not followed (#289).
+      ...(linksOutsideRoot.length > 0 ? { linksOutsideRoot: linksOutsideRoot.length } : {}),
     },
     summary: {
       cssWarnings: cssFindings.length,

package/src/audit/decisions.js

@@ -1,7 +1,8 @@
 'use strict';
 
+const { propertyKindOf } = require('../core/css-vocabulary');
 const { decisionFor } = require('../core/decisions');
-const { formatLength, nearestScaleValues, parseLengthToken, toPx } = require('../core/length');
+const { formatLength, nearestScaleValues, normalizeScale, parseLengthToken, toPx } = require('../core/length');
 
 /**
  * Decisions applied to audit findings, and the plan that proposes them.
@@ -43,18 +44,43 @@ function applyDecisions({ baseFontSize, cssFindings, decisions, tailwindFindings
   return { cssFindings: nextCss, suppressed, summary: { ...summary, suppressed }, tailwindFindings: nextTailwind };
 }
 
+/**
+ * Which scale a finding was checked against, as use-scale picks it: the
+ * `audit.scales` entry for the property's group, else the project scale. The
+ * spacing group's entry is already the project scale (report.js). `key` names
+ * the group when it has a scale of its own; `scalePx` is null for a group set
+ * to "auto", whose scale the rule infers and the audit cannot see (#283).
+ */
+function createFindingScaleResolver({ baseFontSize, groupScales, scale }) {
+  const projectScale = { key: '', scalePx: Array.isArray(scale) ? normalizeScale(scale, baseFontSize) : [] };
+  const byGroup = new Map();
+  for (const [group, entry] of Object.entries(groupScales || {})) {
+    if (group === 'spacing' || !entry) continue;
+    byGroup.set(group, { key: group, scalePx: Array.isArray(entry.scale) ? normalizeScale(entry.scale, baseFontSize) : null });
+  }
+  return (finding) => {
+    if (finding.token || !finding.property) return projectScale;
+    return byGroup.get(propertyKindOf(finding.property)) || projectScale;
+  };
+}
+
 /**
  * One proposed entry per distinct off-scale px value: the most common spelling,
- * how often it occurs, the properties it sits on, the two nearest scale steps,
- * and the decision so far (`undecided` for anything nobody has looked at).
+ * how often it occurs, the properties it sits on, the two nearest steps of the
+ * scale it was checked against, and the decision so far (`undecided` for
+ * anything nobody has looked at). A value found in groups with different
+ * scales (`15px` as a font size and as a padding) gets one entry per scale.
  */
-function buildDecisionPlan({ baseFontSize, decisions, offScaleFindings, scale }) {
+function buildDecisionPlan({ baseFontSize, decisions, groupScales = {}, offScaleFindings, scale }) {
+  const scaleOf = createFindingScaleResolver({ baseFontSize, groupScales, scale });
+  const projectScale = scaleOf({});
   const groups = new Map();
   for (const finding of offScaleFindings) {
     const px = findingPx(finding, baseFontSize);
     if (px === null) continue;
-    const key = String(px);
-    const group = groups.get(key) || { count: 0, properties: new Map(), px, spellings: new Map() };
+    const checkedAgainst = scaleOf(finding);
+    const key = `${px}|${checkedAgainst.key}`;
+    const group = groups.get(key) || { count: 0, properties: new Map(), px, scale: checkedAgainst, spellings: new Map() };
     group.count += 1;
     const spelling = (finding.value || finding.rawValue).trim();
     group.spellings.set(spelling, (group.spellings.get(spelling) || 0) + 1);
@@ -64,35 +90,38 @@ function buildDecisionPlan({ baseFontSize, decisions, offScaleFindings, scale })
   }
 
   const mostCommon = (map) => [...map.entries()].sort((a, b) => b[1] - a[1]).map(([name]) => name);
-  const scalePx = Array.isArray(scale) ? scale.map(Number).filter(Number.isFinite) : [];
-  const nearestFor = (px) => {
-    const nearest = nearestScaleValues(px, scalePx);
+  const nearestFor = (px, scalePx) => {
+    const nearest = scalePx ? nearestScaleValues(px, scalePx) : null;
     return nearest ? [formatLength(nearest.lower, 'px'), formatLength(nearest.upper, 'px')] : [];
   };
+  const groupsForPx = (px) => [...groups.values()].filter((group) => group.px === px);
 
   const entries = [];
   const decided = new Set();
   for (const decision of decisions || []) {
-    const group = groups.get(String(decision.px));
-    decided.add(String(decision.px));
+    const found = groupsForPx(decision.px);
+    decided.add(decision.px);
+    // A decision covers the value on every property it names; its nearest steps
+    // come from the one scale its findings were checked against, if just one.
+    const scales = [...new Set(found.map((group) => group.scale))];
     entries.push({
       value: decision.value,
       decision: decision.decision,
       ...(decision.as ? { as: decision.as } : {}),
       ...(decision.reason ? { reason: decision.reason } : {}),
       ...(decision.properties ? { properties: decision.properties } : {}),
-      count: group ? group.count : 0,
-      nearest: nearestFor(decision.px),
+      count: found.reduce((sum, group) => sum + group.count, 0),
+      nearest: nearestFor(decision.px, (scales.length === 1 ? scales[0] : projectScale).scalePx),
     });
   }
-  for (const [key, group] of groups) {
-    if (decided.has(key)) continue;
+  for (const group of groups.values()) {
+    if (decided.has(group.px)) continue;
     entries.push({
       value: mostCommon(group.spellings)[0],
       decision: 'undecided',
       count: group.count,
       properties: mostCommon(group.properties).slice(0, 3),
-      nearest: nearestFor(group.px),
+      nearest: nearestFor(group.px, group.scale.scalePx),
     });
   }
   entries.sort((a, b) => b.count - a.count || String(a.value).localeCompare(String(b.value)));

package/src/audit/render-markdown.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { sortCountMap } = require('./contract');
-const { escapeMarkdown } = require('./render-utils');
+const { escapeMarkdown, markdownCode, tableCode } = require('./render-utils');
 
 function describeScaleSource(scale) {
   if (scale.rejected) {
@@ -17,7 +17,7 @@ function renderMarkdown(report) {
     '# Rhythmguard Design-System Audit',
     '',
     ...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new.`, ''] : []),
-    `Directory: \`${report.directory}\``,
+    `Directory: ${markdownCode(report.directory)}`,
     '',
     '## Summary',
     '',
@@ -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} |`] : []),
+    ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [`| Symbolic links not followed (they point outside the scanned directory) | ${report.scanned.linksOutsideRoot} |`] : []),
     ...(parseErrors(report).length > 0 ? [`| Stylesheets that failed to parse (not audited) | ${parseErrors(report).length} |`] : []),
     `| Files with issues | ${report.filesWithIssues} |`,
     `| Total findings | ${report.totalWarnings} |`,
@@ -36,7 +37,7 @@ function renderMarkdown(report) {
 
   if (report.scale) {
     lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
-    lines.push(`| Scale source | ${describeScaleSource(report.scale)} |`);
+    lines.push(`| Scale source | ${escapeMarkdown(describeScaleSource(report.scale))} |`);
   }
 
   if (report.decisions) {
@@ -66,7 +67,7 @@ function renderMarkdown(report) {
     lines.push('| File | Findings |');
     lines.push('| --- | ---: |');
     for (const { file, count } of report.topAffectedFiles) {
-      lines.push(`| \`${escapeMarkdown(file)}\` | ${count} |`);
+      lines.push(`| ${tableCode(file)} | ${count} |`);
     }
     lines.push('');
   }
@@ -77,7 +78,7 @@ function renderMarkdown(report) {
     lines.push('| File | Class | Suggested class |');
     lines.push('| --- | --- | --- |');
     for (const finding of report.findings.tailwind.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(`${finding.file}:${finding.line}`)}\` | \`${escapeMarkdown(finding.token)}\` | \`${escapeMarkdown(finding.fixedToken || 'n/a')}\` |`);
+      lines.push(`| ${tableCode(`${finding.file}:${finding.line}`)} | ${tableCode(finding.token)} | ${tableCode(finding.fixedToken || 'n/a')} |`);
     }
     lines.push('');
   }
@@ -115,7 +116,7 @@ function appendParseErrorsMarkdown(lines, report) {
   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(`| ${tableCode(`${finding.file}:${finding.line}:${finding.column}`)} | ${escapeMarkdown(finding.text)} |`);
   }
   lines.push('');
 }
@@ -138,8 +139,8 @@ function appendTokenChainsMarkdown(lines, chains) {
     for (const entry of chains.entries.slice(0, 50)) {
       const detail = entry.reason
         ? entry.reason
-        : entry.terminals.map((terminal) => `\`${terminal}\``).join(', ');
-      lines.push(`| \`${escapeMarkdown(entry.token)}\` | ${entry.outcome} | ${detail}${entry.via.length > 0 ? ` via ${entry.via.map((name) => `\`${name}\``).join(' → ')}` : ''} |`);
+        : entry.terminals.map((terminal) => tableCode(terminal)).join(', ');
+      lines.push(`| ${tableCode(entry.token)} | ${entry.outcome} | ${detail}${entry.via.length > 0 ? ` via ${entry.via.map((name) => tableCode(name)).join(' → ')}` : ''} |`);
     }
     lines.push('');
   }
@@ -164,16 +165,16 @@ function appendTokenLaddersMarkdown(lines, ladders) {
     const flagged = new Map();
     for (const problem of entry.problems) {
       const where = problem.end === 'both' ? '' : ` at ${problem.end}`;
-      const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with \`${problem.tokens[0]}\``;
+      const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with ${tableCode(problem.tokens[0])}`;
       flagged.set(problem.tokens[1], [...(flagged.get(problem.tokens[1]) || []), note]);
     }
-    const aliasNote = entry.aliases ? ` (also aliased as ${entry.aliases.map((alias) => `\`${escapeMarkdown(alias)}\``).join(', ')})` : '';
-    lines.push(`**\`${escapeMarkdown(entry.prefix)}\`**${aliasNote}`);
+    const aliasNote = entry.aliases ? ` (also aliased as ${entry.aliases.map((alias) => markdownCode(alias)).join(', ')})` : '';
+    lines.push(`**${markdownCode(entry.prefix)}**${aliasNote}`);
     lines.push('');
     lines.push('| Token | Min | Max | Problem |');
     lines.push('| --- | --- | --- | --- |');
     for (const step of entry.steps) {
-      lines.push(`| \`${escapeMarkdown(step.token)}\` | ${step.min || 'fluid'} | ${step.max || 'fluid'} | ${(flagged.get(step.token) || []).join('; ')} |`);
+      lines.push(`| ${tableCode(step.token)} | ${step.min || 'fluid'} | ${step.max || 'fluid'} | ${(flagged.get(step.token) || []).join('; ')} |`);
     }
     lines.push('');
   }
@@ -208,7 +209,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| File | Format | Tokens | Warnings |');
     lines.push('| --- | --- | ---: | --- |');
     for (const source of sources.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(source.file)}\` | \`${source.format}\` | ${source.tokenCount} | \`${escapeMarkdown(source.warnings.join('; ') || 'none')}\` |`);
+      lines.push(`| ${tableCode(source.file)} | ${tableCode(source.format)} | ${source.tokenCount} | ${tableCode(source.warnings.join('; ') || 'none')} |`);
     }
     lines.push('');
   }
@@ -219,7 +220,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| Token | Files |');
     lines.push('| --- | --- |');
     for (const entry of missingTokens.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(entry.token)}\` | \`${escapeMarkdown(entry.files.join(', '))}\` |`);
+      lines.push(`| ${tableCode(entry.token)} | ${tableCode(entry.files.join(', '))} |`);
     }
     lines.push('');
   }
@@ -230,7 +231,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| Token | Value |');
     lines.push('| --- | --- |');
     for (const entry of unusedTokens.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(entry.token)}\` | \`${escapeMarkdown((entry.values || []).join(', ') || 'n/a')}\` |`);
+      lines.push(`| ${tableCode(entry.token)} | ${tableCode((entry.values || []).join(', ') || 'n/a')} |`);
     }
     lines.push('');
   }
@@ -241,7 +242,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| Value | Count | Files |');
     lines.push('| --- | ---: | --- |');
     for (const entry of rawValueCandidates.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(entry.value)}\` | ${entry.count} | \`${escapeMarkdown(entry.files.join(', '))}\` |`);
+      lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(entry.files.join(', '))} |`);
     }
     lines.push('');
   }
@@ -252,7 +253,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| Value | Count | Tokens |');
     lines.push('| --- | ---: | --- |');
     for (const entry of rawValueMatches.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(entry.value)}\` | ${entry.count} | \`${escapeMarkdown(entry.tokens.join(', '))}\` |`);
+      lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(entry.tokens.join(', '))} |`);
     }
     lines.push('');
   }
@@ -263,7 +264,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
     lines.push('| Value | Tokens |');
     lines.push('| --- | --- |');
     for (const entry of conflictingTokens.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(entry.value)}\` | \`${escapeMarkdown(entry.tokens.join(', '))}\` |`);
+      lines.push(`| ${tableCode(entry.value)} | ${tableCode(entry.tokens.join(', '))} |`);
     }
     lines.push('');
   }
@@ -290,13 +291,13 @@ function appendBaselineMarkdown(lines, report) {
     lines.push('| New finding | Location |');
     lines.push('| --- | --- |');
     for (const finding of report.baseline.newFindings.slice(0, 10)) {
-      lines.push(`| \`${escapeMarkdown(finding.text)}\` | \`${escapeMarkdown(`${finding.file}:${finding.line}`)}\` |`);
+      lines.push(`| ${tableCode(finding.text)} | ${tableCode(`${finding.file}:${finding.line}`)} |`);
     }
     lines.push('');
   }
 
   if (report.baselineWritten) {
-    lines.push(`Baseline written: \`${escapeMarkdown(report.baselineWritten.file)}\``);
+    lines.push(`Baseline written: ${markdownCode(report.baselineWritten.file)}`);
     lines.push('');
   }
 }
@@ -313,7 +314,7 @@ function appendMarkdownCounts(lines, title, counts, label = 'Value') {
   lines.push(`| ${label} | Count |`);
   lines.push('| --- | ---: |');
   for (const [value, count] of entries) {
-    lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);
+    lines.push(`| ${tableCode(value)} | ${count} |`);
   }
   lines.push('');
 }