stylelint-plugin-rhythmguard 3.10.2 → 3.11.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.11.0] - 2026-10-18
+
+### Fixed
+
+- ESLint `--fix` on `tailwind-class-use-scale` and `tailwind-class-use-motion-scale` no longer rewrites the rest of the string. The fix was built from the decoded value with only the quote re-escaped, so `'p-[13px]\n'` became a string with a real newline that no longer parsed, `\\201C` became an octal escape, `\\` lost its escape and a JSX `"` became `\"`. A fix now replaces only the class token in the source text, and everything else in the literal stays as written. A class with an escape inside it (`p-[13\x70x]`) is still reported but not fixed. Template literals are checked on their decoded text, so a class next to an escape such as `` `p-[13px]\n` `` is now reported; they are still not fixed. ([#225](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/225))
+- `rhythmguard fix` parsed SCSS with the plain CSS parser (`postcss.parse` ignores a `syntax` option), so it rewrote values inside `//` comments (`// old: .card { padding: 10px; }` became `padding: 8px`) and skipped valid SCSS such as a rule with `// note` inside it as `could not parse`. SCSS is now read and written with postcss-scss's own `parse` and `stringify`: comments stay byte-identical and the declarations are fixed. Without postcss-scss an `.scss` file is skipped with `postcss-scss is not installed; install it to rewrite SCSS`. ([#229](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/229))
+- `rhythmguard fix` ignored `.rhythmguardignore` and `audit.ignore`, so `--write` rewrote files the audit never scans: with `legacy` and `vendor/**` ignored, the audit scanned 1 file and `fix` reported `3 replacements in 3 files`. It now loads ignores through the same code as the audit (the ignore file, `audit.ignore`, `audit.ignorePath`) and takes the audit's `--ignore` and `--ignore-path`; generated and vendored directories such as `node_modules` and `dist` stay skipped. Dry run and `--write` list the same files. A file `--decided` cannot read is named once instead of once per decision. ([#230](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/230))
+- `maxFindings` and `minCleanliness` in `.rhythmguardrc.json` now fail the audit. The config was merged into the report but the exit gates read only the command line, so `{"audit":{"maxFindings":0}}` printed findings and exited 0. The gates now read the merged options; a `--max-findings` or `--min-cleanliness` flag still overrides the config, and `--no-config` still ignores it. ([#226](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/226))
+- An invalid `--scale` such as `0;4;8`, `4,abc`, `NaN` or `-4,4,8` is refused with `Invalid --scale value "0;4;8": "0;4;8" is not a non-negative number or length.` and exit 1. Before, Stylelint rejected the option, ran no rule, and the audit reported `No issues found` with every gate passing. `audit.scale` in the config is checked the same way. The audit also stops with Stylelint's own text whenever it rejects any rule option, so no other bad option can switch the audit off. ([#227](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/227))
+- `--staged` and `--since` scan the changed files from any directory. Git printed paths relative to the repository root, which were resolved against the current directory, so a run from a package directory found no files and exited 0; and names with non-ASCII characters came back quoted and were dropped. Git now runs in the scanned directory with `-z`, and paths resolve against the repository top level, so `src/ä b.css` and `src/sp ace.css` are scanned. ([#228](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/228))
+- Negative tokens no longer flip the sign of a fix. Tokens were indexed by their absolute value, so `--space-neg-2: -8px` was offered for `padding: 9px` (writing `var(--space-neg-2)`, which is -8px) and negated for `margin: -9px` (writing `calc(-1 * var(--space-neg-2))`, which is +8px). Token values are now indexed with their sign: a negative token serves only a negative value and is written as is, a positive token is negated for a negative value as before, and a positive value never gets a negative token. Applies to `use-scale` and `no-offscale-transform` with `fixWith: "token"` and to `prefer-token`, including `tokenMapFromCssCustomProperties`, where the last of `--space-2: 8px` and `--space-neg-2: -8px` used to win for both signs. ([#221](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/221))
+- A token with more than one value is no longer written by a fix. `--space-3: 12px` at the root and 20px under `@media (min-width: 768px)`, or `--space-2` redefined under `[data-density=compact]`, was indexed once per value, so `padding: 20px` became `var(--space-3)`, which is 12px on mobile. A token whose definitions resolve to more than one px value (or to a value that is not a plain length) is now left out of the token index and of `tokenMapFromCssCustomProperties`, and the fix writes the literal. The same value in two units (`12px` and `0.75rem`) is still one value. ([#231](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/231))
+- `unitStrategy: "exact"` with `fixWith: "token"` finds the token in the literal's unit. The snapped value, in rem for a rem literal, was compared with the tokens' px values, so `padding: 1.1rem` against a `1rem` step wrote `var(--space-a)` (`0.0625rem`, 1px) instead of `var(--space-1)` (`1rem`). The lookup now converts the snapped value to px first. Applies to `use-scale` and `no-offscale-transform`. ([#223](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/223))
+- An invalid `tokenPattern` (`"["`) is reported again instead of aborting the Stylelint run. `use-scale` and `prefer-token` reported it without a node, which Stylelint rejects with an error about position arguments; the report is now made on the root, once per file, and the file is linted with the default pattern as the option docs describe. ([#222](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/222))
+- Autofix converges when `baseFontSize` is not 16. A fix writes rem and em with four decimals, so `0.7rem` at base 18 became `0.6667rem` (12.0006px), and the next run reported that value as off scale because the on-scale check allowed only 0.0001px. A rem or em value is now on the scale when it is within the rounding of four decimals at the base font size (0.00005 of the base, plus the old tolerance); px values are compared as before. Fix then re-lint is clean at base 10, 12, 14, 18 and 20 in `use-scale`, `no-offscale-transform`, `prefer-token`'s numeric scale check and the ESLint Tailwind rule. ([#224](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/224))
+
+### Messages
+
+- `use-scale` and `no-offscale-transform` with `fixWith: "token"`: when a negative token is written as is for a negative literal, the note gives the signed value, `var(--space-neg-2) holds -8px.` A positive token negated for a negative literal still reads `var(--space-3) holds 12px.` ([#221](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/221))
+- `prefer-token`: a negative literal that a negative token holds now reads `Use var(--space-neg-2).`, where it read `Use calc(-1 * var(--space-neg-2)).`; a positive literal is no longer offered a negative token. A token that holds more than one value is no longer named, so such a value reads `No known token holds this value; use the nearest token or add one.` ([#221](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/221), [#231](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/231))
+
 ## [3.10.2] - 2026-10-15
 
 ### Messages

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

@@ -4,6 +4,7 @@ const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
 } = require('../core/token-sources');
+const { isScaleEntry } = require('../core/options');
 const { BADGE_METRICS } = require('./render-badge');
 const {
   VALID_FORMATS,
@@ -223,9 +224,9 @@ function parseTokenSourcePaths(raw) {
 }
 
 
-function parseScale(raw) {
+function parseScale(raw, optionName = '--scale') {
   if (!raw) {
-    throw new Error('Missing value for --scale.');
+    throw new Error(`Missing value for ${optionName}.`);
   }
 
   if (raw.trim().toLowerCase() === 'auto') {
@@ -240,10 +241,28 @@ function parseScale(raw) {
       return Number.isFinite(numeric) && !/[a-z%]/i.test(part) ? numeric : part;
     });
 
+  return validateScale(scale, optionName, raw);
+}
+
+/**
+ * A scale reaches Stylelint as the use-scale `scale` option, and Stylelint
+ * answers an invalid entry with an option warning and no findings at all. Check
+ * every entry the way the rule does, so a typo fails here, by name.
+ */
+function validateScale(scale, optionName = '--scale', raw = scale) {
   if (scale.length === 0) {
     throw new Error('Scale must include at least one value.');
   }
 
+  const invalid = scale.find((entry) => !isScaleEntry(entry));
+  if (invalid !== undefined) {
+    const shown = Array.isArray(raw) ? JSON.stringify(raw) : `"${raw}"`;
+    throw new Error(
+      `Invalid ${optionName} value ${shown}: "${invalid}" is not a non-negative number or length. `
+      + 'Use comma-separated values such as 0,4,8,12,16, or auto.',
+    );
+  }
+
   return scale;
 }
 
@@ -268,4 +287,5 @@ module.exports = {
   parsePositiveInteger,
   parseScale,
   parseTokenSourcePaths,
+  validateScale,
 };

package/src/audit/codemod.js

@@ -77,21 +77,31 @@ function declarationValueOffset(decl) {
   return decl.prop.length + between.length;
 }
 
+/**
+ * Parse with the syntax that will write the file back. SCSS goes through
+ * postcss-scss's own parse and stringify: `postcss.parse` ignores a `syntax`
+ * option, so it would read `// a: 10px` as a declaration and rewrite it.
+ * Returns null for SCSS when postcss-scss cannot be resolved; such a file is
+ * skipped, never parsed as CSS.
+ */
 function parseStylesheet(filePath, source) {
   if (isScssFile(filePath)) {
     const syntaxPath = resolveScssSyntax();
     if (!syntaxPath) {
       return null;
     }
-    return postcss.parse(source, { from: filePath, syntax: require(syntaxPath) });
+    const syntax = require(syntaxPath);
+    return { root: syntax.parse(source, { from: filePath }), syntax };
   }
-  return postcss.parse(source, { from: filePath });
+  return { root: postcss.parse(source, { from: filePath }), syntax: null };
 }
 
 /**
  * Apply one replacement across a directory. Dry run unless `write`; returns
  * the per-file changes and which files were skipped (unparseable, or SCSS
- * without postcss-scss).
+ * without postcss-scss). `ignorePatterns` are root-relative paths and globs,
+ * as the audit takes them; the audit's generated and vendored directories
+ * (node_modules, dist, build and the rest of SKIP_DIRS) are always skipped.
  */
 function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties = null, px, replacement, write = false }) {
   const rootDir = path.resolve(process.cwd(), dir);
@@ -100,23 +110,24 @@ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties =
   const skipped = [];
   for (const filePath of files) {
     const source = fs.readFileSync(filePath, 'utf8');
-    let root;
+    let parsed;
     try {
-      root = parseStylesheet(filePath, source);
+      parsed = parseStylesheet(filePath, source);
     } catch {
       skipped.push({ file: formatPath(filePath), reason: 'could not parse' });
       continue;
     }
-    if (!root) {
-      skipped.push({ file: formatPath(filePath), reason: 'install postcss-scss to rewrite SCSS' });
+    if (!parsed) {
+      skipped.push({ file: formatPath(filePath), reason: 'postcss-scss is not installed; install it to rewrite SCSS' });
       continue;
     }
+    const { root, syntax } = parsed;
     const changes = replaceLength(root, { baseFontSize, properties, px, replacement });
     if (changes.length === 0) {
       continue;
     }
     if (write) {
-      fs.writeFileSync(filePath, root.toString());
+      fs.writeFileSync(filePath, syntax ? root.toString(syntax) : root.toString());
     }
     results.push({ changes, file: formatPath(filePath) });
   }

package/src/audit/config.js

@@ -15,6 +15,7 @@ const {
   parsePercentage,
   parsePositiveInteger,
   parseScale,
+  validateScale,
 } = require('./args');
 const {
   DEFAULT_IGNORE_PATH,
@@ -117,9 +118,9 @@ function applyAuditConfig(parsed, configResult) {
   }
   applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
     if (Array.isArray(value)) {
-      return value;
+      return validateScale(value, 'audit.scale');
     }
-    return parseScale(String(value));
+    return parseScale(String(value), 'audit.scale');
   });
 
   next.decisions = normalizeDecisions(configResult.decisions, { baseFontSize: next.baseFontSize });
@@ -240,6 +241,19 @@ function loadIgnorePatterns(ignorePath) {
     .filter(Boolean);
 }
 
+/**
+ * The ignore list a run uses: the ignore file (.rhythmguardignore unless
+ * --ignore-path or audit.ignorePath names another), then audit.ignore and
+ * --ignore. `parsed` is the options after applyAuditConfig. The audit and
+ * `rhythmguard fix` both call this, so they never disagree on what is skipped.
+ */
+function resolveIgnorePatterns(parsed) {
+  return [
+    ...loadIgnorePatterns(parsed.ignorePath),
+    ...parsed.ignorePatterns,
+  ];
+}
+
 module.exports = {
   applyAuditConfig,
   applyConfigScalar,
@@ -248,4 +262,5 @@ module.exports = {
   normalizeCliTokenSources,
   normalizeConfigTokenSources,
   parseBooleanOption,
+  resolveIgnorePatterns,
 };

package/src/audit/report.js

@@ -14,7 +14,7 @@ const { createDefaultAuditOptions } = require('./shared');
 const {
   applyAuditConfig,
   loadAuditConfig,
-  loadIgnorePatterns,
+  resolveIgnorePatterns,
 } = require('./config');
 const { buildReport, collectTokenDefinitions } = require('./contract');
 const { DEFAULT_SCALE, formatPath } = require('./shared');
@@ -34,11 +34,7 @@ const { collectTailwindFindings, collectTailwindMotionFindings } = require('./sc
 async function createAuditReport(options) {
   const parsed = normalizeCreateAuditOptions(options);
   const resolvedDir = assertDirectory(parsed.dir);
-  let ignorePatterns;
-  ignorePatterns = [
-    ...loadIgnorePatterns(parsed.ignorePath),
-    ...parsed.ignorePatterns,
-  ];
+  const ignorePatterns = resolveIgnorePatterns(parsed);
 
   const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
 

package/src/audit/scan/files.js

@@ -77,34 +77,36 @@ function getScanFiles(rootDir, ignorePatterns, parsed) {
 }
 
 function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
-  const args = parsed.staged
-    ? ['diff', '--name-only', '--cached', '--diff-filter=ACMR', '--']
-    : ['diff', '--name-only', '--diff-filter=ACMR', parsed.since, '--'];
-  let output;
-
-  try {
-    output = execFileSync('git', args, {
-      cwd: process.cwd(),
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-  } catch (err) {
-    const stderr = err.stderr ? String(err.stderr).trim() : err.message;
-    throw new Error(`Unable to read changed files from git: ${stderr}`, { cause: err });
+  // -z prints names raw and NUL-separated: no quoting of spaces or non-ASCII
+  // bytes. diff.relative is pinned off so every name is relative to the
+  // repository top level, whatever the user's git config says.
+  const diffArgs = parsed.staged
+    ? ['diff', '--name-only', '-z', '--cached', '--diff-filter=ACMR', '--']
+    : ['diff', '--name-only', '-z', '--diff-filter=ACMR', parsed.since, '--'];
+  // Git runs in the scanned directory, so the repository is the one that holds
+  // the files, whichever directory the command was started from.
+  const topLevel = runGit(rootDir, ['rev-parse', '--show-toplevel']).replace(/\r?\n$/, '');
+  const output = runGit(rootDir, ['-c', 'diff.relative=false', ...diffArgs]);
+
+  // git reports the top level with symlinks resolved (/private/var on macOS);
+  // compare in that form, then name files under the directory as it was given.
+  const realRootDir = fs.realpathSync(rootDir);
+  const changedFiles = output.split('\0').filter(Boolean);
+  const changedPaths = [];
+  for (const filePath of changedFiles) {
+    const realPath = path.resolve(topLevel, filePath);
+    if (isPathInside(realRootDir, realPath)) {
+      changedPaths.push(path.join(rootDir, path.relative(realRootDir, realPath)));
+    }
   }
 
   const cssFiles = [];
   const templateFiles = [];
   const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
   const seen = new Set();
-  const changedFiles = output.split(/\r?\n/)
-    .map((filePath) => filePath.trim())
-    .filter(Boolean);
-
-  for (const filePath of changedFiles) {
-    const fullPath = path.resolve(process.cwd(), filePath);
 
-    if (!isPathInside(rootDir, fullPath) || seen.has(fullPath) || !fs.existsSync(fullPath)) {
+  for (const fullPath of changedPaths) {
+    if (seen.has(fullPath) || !fs.existsSync(fullPath)) {
       continue;
     }
 
@@ -137,6 +139,19 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
   };
 }
 
+function runGit(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const stderr = err.stderr ? String(err.stderr).trim() : err.message;
+    throw new Error(`Unable to read changed files from git: ${stderr}`, { cause: err });
+  }
+}
+
 function isPathInside(rootDir, filePath) {
   const relativePath = path.relative(rootDir, filePath);
   return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));

package/src/audit/scan/stylesheets.js

@@ -113,6 +113,8 @@ async function runStylelintAudit(cssFiles, options) {
     }
   }
 
+  assertNoInvalidOptions(results);
+
   results.scssFiles = scssFiles.length;
   results.scssSkipped = scssSkipped;
   // Stylelint returns no result at all for a file its ignore file excludes, so
@@ -122,6 +124,24 @@ async function runStylelintAudit(cssFiles, options) {
   return results;
 }
 
+/**
+ * Stylelint does not run a rule whose options it rejects: it reports an
+ * invalidOptionWarning and no findings for that rule. Read as findings, that is
+ * a clean audit and a passing gate, so any rejected option stops the run.
+ */
+function assertNoInvalidOptions(results) {
+  const texts = new Set();
+  for (const result of results) {
+    for (const warning of result.invalidOptionWarnings || []) {
+      texts.add(warning.text);
+    }
+  }
+
+  if (texts.size > 0) {
+    throw new Error(`Stylelint rejected the audit's rule options, so no findings could be collected: ${Array.from(texts).join('; ')}`);
+  }
+}
+
 function collectCssFindings(fileResults) {
   const findings = [];
   const sources = new Map();

package/src/cli/audit.js

@@ -17,7 +17,7 @@ const { renderBadge } = require('../audit/render-badge');
 const { renderHtml } = require('../audit/render-html');
 const { renderMarkdown } = require('../audit/render-markdown');
 const { renderText } = require('../audit/render-text');
-const { createAuditReport } = require('../audit/report');
+const { createAuditReport, normalizeCreateAuditOptions } = require('../audit/report');
 
 const args = process.argv.slice(3);
 
@@ -41,8 +41,12 @@ async function run() {
   }
 
   let report;
+  let options;
   try {
-    report = await createAuditReport(parsed);
+    // Apply .rhythmguardrc.json once, here, so the exit gates (maxFindings,
+    // minCleanliness) read the same merged options the report was built from.
+    options = { ...normalizeCreateAuditOptions(parsed), configApplied: true };
+    report = await createAuditReport(options);
   } catch (err) {
     process.stderr.write(`${err.message}\n`);
     process.exit(1);
@@ -53,7 +57,7 @@ async function run() {
     return;
   }
 
-  const auditFailures = getAuditFailures(report, parsed);
+  const auditFailures = getAuditFailures(report, options);
 
   if (parsed.format === 'json') {
     writeOutput(`${JSON.stringify(toAuditContractReport(report), null, 2)}\n`, parsed.outputPath);

package/src/cli/fix.js

@@ -2,7 +2,14 @@
 
 const { loadRcDecisions } = require('../core/decisions');
 const { parseLengthToken, toPx } = require('../core/length');
+const { OPTIONS: AUDIT_OPTIONS } = require('../audit/args');
 const { runCodemod } = require('../audit/codemod');
+const { resolveIgnorePatterns } = require('../audit/config');
+const { normalizeCreateAuditOptions } = require('../audit/report');
+const { DEFAULT_IGNORE_PATH } = require('../audit/shared');
+
+// --ignore and --ignore-path are the audit's own flags, parsed by the audit's table.
+const IGNORE_OPTIONS = AUDIT_OPTIONS.filter((option) => option.flag === '--ignore' || option.flag === '--ignore-path');
 
 const HELP = `Usage: rhythmguard fix <dir> --value <length> --to <replacement> [options]
        rhythmguard fix <dir> --decided [options]
@@ -11,7 +18,9 @@ Replace one spacing literal everywhere it appears on a spacing property, or
 execute the snap decisions in .rhythmguardrc.json that name a "to". Matching is
 by px, so --value 10px also rewrites 0.625rem. Token definitions, values inside
 var()/theme()/token(), and non-spacing properties are never touched. Dry run by
-default.
+default. Files the audit skips are skipped too: .rhythmguardignore, audit.ignore
+in .rhythmguardrc.json, --ignore, and generated or vendored directories such as
+node_modules and dist.
 
 Options:
   --value <length>       The literal to replace, for example 10px or 0.625rem
@@ -19,16 +28,32 @@ Options:
   --decided              Apply every snap decision that has a "to"
   --properties <list>    Comma-separated property names or prefix-* patterns (default: spacing properties)
   --base-font-size <px>  Base for rem/em conversion (default: 16)
+  --ignore <pattern>     Exclude a root-relative path or glob (repeatable, comma-separated)
+  --ignore-path <file>   Load ignore patterns from file (default: .rhythmguardignore when present)
   --write                Apply the changes; without it, only list them
   --help                 Show this help message
 `;
 
 function parseArgs(argv) {
-  const parsed = { baseFontSize: 16, decided: false, dir: null, help: false, properties: null, replacement: null, value: null, write: false };
+  const parsed = {
+    baseFontSize: 16,
+    cliOptions: new Set(),
+    decided: false,
+    dir: null,
+    help: false,
+    ignorePath: DEFAULT_IGNORE_PATH,
+    ignorePatterns: [],
+    properties: null,
+    replacement: null,
+    value: null,
+    write: false,
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     const next = () => argv[++index];
-    if (arg === '--help' || arg === '-h') parsed.help = true;
+    const ignoreOption = IGNORE_OPTIONS.find((option) => arg === option.flag || arg.startsWith(`${option.flag}=`));
+    if (ignoreOption) ignoreOption.apply(parsed, arg === ignoreOption.flag ? next() : arg.slice(ignoreOption.flag.length + 1));
+    else if (arg === '--help' || arg === '-h') parsed.help = true;
     else if (arg === '--write') parsed.write = true;
     else if (arg === '--decided') parsed.decided = true;
     else if (arg === '--value') parsed.value = next();
@@ -61,6 +86,19 @@ function lengthToPx(value, baseFontSize) {
   return px;
 }
 
+/**
+ * The ignore list, loaded exactly as the audit loads it: .rhythmguardrc.json's
+ * audit.ignore and audit.ignorePath, the ignore file, then --ignore.
+ */
+function auditIgnorePatterns(parsed) {
+  return resolveIgnorePatterns(normalizeCreateAuditOptions({
+    cliOptions: parsed.cliOptions,
+    dir: parsed.dir,
+    ignorePath: parsed.ignorePath,
+    ignorePatterns: parsed.ignorePatterns,
+  }));
+}
+
 /** The replacements to run: one from --value/--to, or every snap decision with a "to". */
 function plannedReplacements(parsed) {
   if (parsed.decided) {
@@ -98,8 +136,10 @@ function run() {
   }
 
   let plan;
+  let ignorePatterns;
   try {
     plan = plannedReplacements(parsed);
+    ignorePatterns = auditIgnorePatterns(parsed);
   } catch (error) {
     process.stderr.write(`${error.message}\n`);
     process.exit(1);
@@ -108,11 +148,12 @@ function run() {
   const lines = [];
   let total = 0;
   const touched = new Set();
-  const skipped = [];
+  const skipped = new Map();
   for (const replacement of plan.replacements) {
     const outcome = runCodemod({
       baseFontSize: parsed.baseFontSize,
       dir: parsed.dir,
+      ignorePatterns,
       properties: parsed.properties,
       px: replacement.px,
       replacement: replacement.replacement,
@@ -125,7 +166,10 @@ function run() {
         lines.push(`  ${result.file}:${change.line}:${change.column}  ${change.property}: ${change.from} -> ${change.to}`);
       }
     }
-    skipped.push(...outcome.skipped);
+    // --decided runs once per decision; a file that cannot be read is named once
+    for (const entry of outcome.skipped) {
+      skipped.set(entry.file, entry);
+    }
   }
 
   if (lines.length > 0) {
@@ -138,7 +182,7 @@ function run() {
     const noun2 = plan.skippedSnaps.length === 1 ? 'snap decision has' : 'snap decisions have';
     lines.push(`${plan.skippedSnaps.length} ${noun2} no "to" and ${plan.skippedSnaps.length === 1 ? 'was' : 'were'} skipped: ${plan.skippedSnaps.join(', ')}`);
   }
-  for (const entry of skipped) {
+  for (const entry of skipped.values()) {
     lines.push(`skipped ${entry.file}: ${entry.reason}`);
   }
   process.stdout.write(`${lines.join('\n')}\n`);

package/src/core/length.js

@@ -93,6 +93,20 @@ function numbersEqual(a, b) {
   return Math.abs(a - b) < EPSILON;
 }
 
+/**
+ * Whether a px value is one of the scale steps. A fix writes rem and em with
+ * four decimals, so at a base font size other than 16 the written value can
+ * sit up to half a unit in the fourth decimal off the step: 0.6667rem at an
+ * 18px base is 12.0006px. For those units the comparison allows exactly that
+ * much, so a value a fix wrote is on the scale on the next run (issue #224).
+ */
+function pxOnScale(scalePx, px, unit, baseFontSize) {
+  const tolerance = unit === 'rem' || unit === 'em'
+    ? EPSILON + 0.00005 * Math.abs(baseFontSize)
+    : EPSILON;
+  return scalePx.some((entry) => Math.abs(entry - px) < tolerance);
+}
+
 function normalizeScale(scale, baseFontSize) {
   const normalized = [];
 
@@ -222,5 +236,6 @@ module.exports = {
   normalizeScaleByUnit,
   numbersEqual,
   parseLengthToken,
+  pxOnScale,
   toPx,
 };

package/src/core/options.js

@@ -809,5 +809,6 @@ module.exports = {
   createPropertyScaleResolver,
   isGroupScalesMap,
   isPlainObject,
+  isScaleEntry,
   resolvePropertyScale,
 };

package/src/core/tailwind-class-analysis.js

@@ -6,8 +6,8 @@ const {
   nearestScaleValues,
   nearestText,
   normalizeScale,
-  numbersEqual,
   parseLengthToken,
+  pxOnScale,
   toPx,
 } = require('./length');
 
@@ -187,7 +187,7 @@ function analyzeClassToken(token, options, scalePx) {
     return null;
   }
 
-  const isOnScale = scalePx.some((entry) => numbersEqual(entry, pxValue));
+  const isOnScale = pxOnScale(scalePx, pxValue, parsedLength.unit, options.baseFontSize);
   if (isOnScale) {
     return null;
   }