stylelint-plugin-rhythmguard 3.10.2 → 3.12.0

package/src/audit/token-chains.js

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const { formatLength, numbersEqual, parseLengthToken, toPx } = require('../core/length');
-const { customPropertyDeclarations, parseTokenValueLength } = require('../core/token-sources');
+const { customPropertyDeclarations, hasLineComments, parseTokenValueLength } = require('../core/token-sources');
 const { formatPath } = require('./shared');
 
 /**
@@ -33,7 +33,7 @@ function isSpacingTokenName(token) {
 }
 
 /** Every custom property declaration the audit can see: scanned stylesheets plus external token definitions. */
-function collectDeclarations({ cssFiles, externalDefinitions, skipFile = () => false }) {
+function collectDeclarations({ cssFiles, externalDefinitions, readSource = (file) => fs.readFileSync(file, 'utf8'), skipFile = () => false }) {
   const declarations = new Map();
   const add = (token, value) => {
     if (!declarations.has(token)) declarations.set(token, new Set());
@@ -43,11 +43,12 @@ function collectDeclarations({ cssFiles, externalDefinitions, skipFile = () => f
     if (skipFile(formatPath(filePath))) continue;
     let source;
     try {
-      source = fs.readFileSync(filePath, 'utf8');
+      source = readSource(filePath);
     } catch {
       continue;
     }
-    for (const declaration of customPropertyDeclarations(source)) add(declaration.token, declaration.value);
+    const lineComments = hasLineComments(filePath);
+    for (const declaration of customPropertyDeclarations(source, { lineComments })) add(declaration.token, declaration.value);
   }
   for (const definition of (externalDefinitions || new Map()).values()) {
     if (!definition.token.startsWith('--')) continue;
@@ -56,21 +57,31 @@ function collectDeclarations({ cssFiles, externalDefinitions, skipFile = () => f
   return declarations;
 }
 
-function resolveTokenChains({ baseFontSize = 16, declarations, scale }) {
+/**
+ * `declarations` are the tokens reported on; `references` are looked up only,
+ * so a chain can end in a token package or a token of another kind without
+ * that token becoming an entry of its own (issue #259).
+ */
+function resolveTokenChains({ baseFontSize = 16, declarations, references = null, scale }) {
   const scalePx = (scale || []).map(Number).filter(Number.isFinite);
   const memo = new Map();
+  const declared = (token) => declarations.get(token) || (references ? references.get(token) : undefined);
 
   const classifyValue = (raw, stack, via) => {
     const value = String(raw).trim();
     const length = parseTokenValueLength(value) || parseLengthToken(value);
     if (length && !/^var\(/i.test(value)) {
+      // A non-zero number without a unit (`--space-ratio: 1.5`) is a ratio, not 1.5px (issue #268).
+      if (length.unit === '' && length.number !== 0) {
+        return { outcomes: ['non-length'], terminals: [] };
+      }
       const px = toPx(Math.abs(length.number), length.unit || 'px', baseFontSize);
       return px === null ? { outcomes: ['non-length'], terminals: [] } : { outcomes: [], terminals: [formatLength(px, 'px')] };
     }
     const reference = value.match(VAR_REFERENCE);
     if (reference) {
       const [, target, fallback] = reference;
-      if (declarations.has(target)) {
+      if (declared(target)) {
         via.push(target);
         return resolve(target, stack);
       }
@@ -90,7 +101,7 @@ function resolveTokenChains({ baseFontSize = 16, declarations, scale }) {
     if (stack.includes(token)) {
       return { outcomes: ['unresolved'], reason: `cycle through \`${stack[stack.length - 1]}\``, terminals: [], via: [] };
     }
-    const values = declarations.get(token);
+    const values = declared(token);
     if (!values) return { outcomes: ['unresolved'], reason: `\`${token}\` is not declared`, terminals: [], via: [] };
     const nextStack = [...stack, token];
     const outcomes = new Set();

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/doctor.js

@@ -2,6 +2,9 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { applyAuditConfig, loadAuditConfig, resolveIgnorePatterns } = require('../audit/config');
+const { createDefaultAuditOptions } = require('../audit/shared');
+const { normalizeDecisions } = require('../core/decisions');
 const { normalizeTokenSourceFormat } = require('../core/token-sources');
 
 const cwd = process.cwd();
@@ -221,18 +224,56 @@ function checkRhythmguardConfig() {
     return;
   }
 
-  const audit = parsed.audit;
-  if (!audit || typeof audit !== 'object' || Array.isArray(audit)) {
-    fail('.rhythmguardrc.json audit config missing', 'Add an "audit" object or remove the config file');
-    return;
+  // Validate with the audit's own loader, so doctor passes exactly the files
+  // `rhythmguard audit` accepts. The "audit" section is optional there too.
+  // Decisions are checked on their own, so an error in one section does not
+  // hide an error in the other.
+  let configResult = null;
+  let options = null;
+  try {
+    configResult = loadAuditConfig({});
+    const applied = applyAuditConfig(
+      { ...createDefaultAuditOptions(), cliOptions: new Set() },
+      { ...configResult, decisions: undefined },
+    );
+    resolveIgnorePatterns(applied);
+    options = applied;
+    pass('.rhythmguardrc.json audit config valid');
+  } catch (err) {
+    fail(
+      `.rhythmguardrc.json audit config invalid: ${err.message}`,
+      'Fix the "audit" section; rhythmguard audit stops on the same error',
+    );
   }
 
-  pass('.rhythmguardrc.json audit config valid');
-  checkRhythmguardTokenSources(audit, path.dirname(configPath));
-  checkRhythmguardMotionConfig(audit);
+  checkRhythmguardDecisions(parsed, options ? options.baseFontSize : undefined);
+
+  const audit = configResult ? configResult.audit : {};
+  if (options) {
+    checkRhythmguardTokenSources(audit, path.dirname(configPath));
+    checkRhythmguardMotionConfig(audit);
+  }
   checkRhythmguardBaseline(audit);
 }
 
+function checkRhythmguardDecisions(config, baseFontSize) {
+  const raw = config && typeof config === 'object' && !Array.isArray(config) ? config.decisions : undefined;
+  if (raw === undefined || raw === null) {
+    skip('decisions check skipped (not configured)');
+    return;
+  }
+
+  try {
+    const decisions = normalizeDecisions(raw, baseFontSize === undefined ? {} : { baseFontSize });
+    pass(`.rhythmguardrc.json decisions valid (${decisions.length} decision${decisions.length === 1 ? '' : 's'})`);
+  } catch (err) {
+    fail(
+      `.rhythmguardrc.json decisions invalid: ${err.message}`,
+      'Fix the "decisions" section; rhythmguard audit and the Stylelint rules read the same entries',
+    );
+  }
+}
+
 function checkRhythmguardTokenSources(audit, baseDir) {
   if (audit.tokenSources === undefined) {
     skip('token source config check skipped (not configured)');

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,25 +148,26 @@ function run() {
   const lines = [];
   let total = 0;
   const touched = new Set();
-  const skipped = [];
-  for (const replacement of plan.replacements) {
-    const outcome = runCodemod({
+  // Every replacement in one pass over the original values: a value one snap
+  // writes is never snapped again, and the dry run lists exactly what --write writes.
+  const outcome = plan.replacements.length === 0
+    ? { results: [], skipped: [] }
+    : runCodemod({
       baseFontSize: parsed.baseFontSize,
       dir: parsed.dir,
+      ignorePatterns,
       properties: parsed.properties,
-      px: replacement.px,
-      replacement: replacement.replacement,
+      replacements: plan.replacements,
       write: parsed.write,
     });
-    for (const result of outcome.results) {
-      touched.add(result.file);
-      for (const change of result.changes) {
-        total += 1;
-        lines.push(`  ${result.file}:${change.line}:${change.column}  ${change.property}: ${change.from} -> ${change.to}`);
-      }
+  for (const result of outcome.results) {
+    touched.add(result.file);
+    for (const change of result.changes) {
+      total += 1;
+      lines.push(`  ${result.file}:${change.line}:${change.column}  ${change.property}: ${change.from} -> ${change.to}`);
     }
-    skipped.push(...outcome.skipped);
   }
+  const skipped = outcome.skipped;
 
   if (lines.length > 0) {
     lines.push('');

package/src/cli/init.js

@@ -72,23 +72,117 @@ function detect() {
     fs.existsSync(path.join(cwd, 'next.config.mjs')) ||
     fs.existsSync(path.join(cwd, 'next.config.ts'));
 
-  const hasExistingConfig =
-    fs.existsSync(path.join(cwd, '.stylelintrc')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.json')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.js')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.cjs')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.mjs')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.yml')) ||
-    fs.existsSync(path.join(cwd, '.stylelintrc.yaml')) ||
-    fs.existsSync(path.join(cwd, 'stylelint.config.js')) ||
-    fs.existsSync(path.join(cwd, 'stylelint.config.cjs')) ||
-    fs.existsSync(path.join(cwd, 'stylelint.config.mjs')) ||
-    Boolean(pkg.stylelint);
+  const activeConfig = findActiveStylelintConfig(cwd);
+  const hasExistingConfig = activeConfig !== null;
 
   const tailwind = hasTailwindConfig || hasTailwindDep;
   const nextjs = hasNextConfig;
 
-  return { tailwind, nextjs, hasExistingConfig };
+  return { activeConfig, tailwind, nextjs, hasExistingConfig };
+}
+
+/**
+ * Where Stylelint looks for a config in one directory, in its order. Stylelint
+ * searches with cosmiconfig and does not expose the file it picks, so this is
+ * cosmiconfig 9's default list for the module name "stylelint". The first hit
+ * wins: package.json counts only with a "stylelint" key, and an empty file is
+ * skipped, as cosmiconfig skips it.
+ */
+const STYLELINT_SEARCH_PLACES = [
+  'package.json',
+  '.stylelintrc',
+  '.stylelintrc.json',
+  '.stylelintrc.yaml',
+  '.stylelintrc.yml',
+  '.stylelintrc.js',
+  '.stylelintrc.ts',
+  '.stylelintrc.cjs',
+  '.stylelintrc.mjs',
+  '.config/stylelintrc',
+  '.config/stylelintrc.json',
+  '.config/stylelintrc.yaml',
+  '.config/stylelintrc.yml',
+  '.config/stylelintrc.js',
+  '.config/stylelintrc.ts',
+  '.config/stylelintrc.cjs',
+  '.config/stylelintrc.mjs',
+  'stylelint.config.js',
+  'stylelint.config.ts',
+  'stylelint.config.cjs',
+  'stylelint.config.mjs',
+];
+
+/**
+ * The config file Stylelint loads in `cwd`, or null. `kind` says what init can
+ * do with it: 'json' is rewritten in place; 'package' (the package.json key),
+ * 'yaml' and 'code' (JS or TS) get a snippet to add by hand, because writing a
+ * .stylelintrc.json next to them changes nothing: Stylelint never reads it.
+ */
+function findActiveStylelintConfig(cwd = process.cwd()) {
+  for (const file of STYLELINT_SEARCH_PLACES) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(cwd, file), 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (file === 'package.json') {
+      let pkg = null;
+      try {
+        pkg = JSON.parse(content);
+      } catch {
+        // cosmiconfig would throw here; a broken package.json is no Stylelint config
+      }
+      if (pkg && typeof pkg === 'object' && pkg.stylelint !== undefined && pkg.stylelint !== null) {
+        return { file, kind: 'package' };
+      }
+      continue;
+    }
+
+    if (content.trim() === '') {
+      continue;
+    }
+
+    return { file, kind: configKind(file, content) };
+  }
+
+  return null;
+}
+
+function configKind(file, content) {
+  const extension = path.extname(file);
+  if (extension === '.json') {
+    return 'json';
+  }
+  if (extension === '.yaml' || extension === '.yml') {
+    return 'yaml';
+  }
+  if (extension === '') {
+    // .stylelintrc holds JSON or YAML; only JSON is rewritten.
+    try {
+      JSON.parse(content);
+      return 'json';
+    } catch {
+      return 'yaml';
+    }
+  }
+  return 'code';
+}
+
+/** What to add to a config init cannot rewrite, in that file's own syntax. */
+function configSnippet(kind, config) {
+  if (kind === 'package') {
+    return JSON.stringify({ stylelint: config }, null, 2).split('\n').slice(1, -1).map((line) => line.slice(2)).join('\n');
+  }
+  if (kind === 'yaml') {
+    return Object.entries(config)
+      .map(([key, values]) => `${key}:\n${values.map((value) => `  - ${JSON.stringify(value)}`).join('\n')}`)
+      .join('\n');
+  }
+  return Object.entries(config)
+    .map(([key, values]) => `${key}: ${JSON.stringify(values)},`)
+    .join('\n');
 }
 
 function selectProfile(stack) {
@@ -193,6 +287,31 @@ async function run() {
       process.stdout.write('Detected: plain CSS project\n');
     }
 
+    const profile = selectProfile(stack);
+    const config = {
+      extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
+      // Next.js build output is generated CSS; never lint it.
+      ...(stack.nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
+    };
+
+    // A .stylelintrc.json next to the config Stylelint actually loads is either
+    // never read (package.json, a YAML .stylelintrc) or silently takes over
+    // from it (YAML, JS and TS files later in the search). When that config is
+    // not JSON, say what to add to it and write nothing.
+    const active = stack.activeConfig;
+    if (active && active.kind !== 'json') {
+      const where = active.kind === 'package' ? 'the "stylelint" key in package.json' : active.file;
+      const shadowsJson = STYLELINT_SEARCH_PLACES.indexOf(active.file) < STYLELINT_SEARCH_PLACES.indexOf('.stylelintrc.json');
+      process.stdout.write(`\nProfile: ${profile}\n`);
+      process.stdout.write(shadowsJson
+        ? `\n⚠ Stylelint loads ${where} before .stylelintrc.json, so it would never read a .stylelintrc.json.\n`
+        : `\n⚠ Stylelint loads ${where}; a new .stylelintrc.json would replace it and leave it unused.\n`);
+      process.stdout.write(`Add this to ${active.kind === 'package' ? 'package.json' : active.file}, merging with what is there:\n\n`);
+      process.stdout.write(`${configSnippet(active.kind, config)}\n\n`);
+      process.stdout.write('Nothing was written.\n\n');
+      return;
+    }
+
     // Warn about existing config
     if (stack.hasExistingConfig) {
       process.stdout.write('\n⚠ Existing Stylelint config found.\n');
@@ -203,22 +322,16 @@ async function run() {
       }
     }
 
-    const profile = selectProfile(stack);
     process.stdout.write(`\nProfile: ${profile}\n`);
 
-    const answer = await prompter.ask('Write .stylelintrc.json? (y/n) ');
+    const targetFile = active ? active.file : '.stylelintrc.json';
+    const answer = await prompter.ask(`Write ${targetFile}? (y/n) `);
     if (answer !== 'y' && answer !== 'yes') {
       process.stdout.write('Aborted.\n');
       process.exit(0);
     }
 
-    const config = {
-      extends: [`stylelint-plugin-rhythmguard/configs/${profile}`],
-      // Next.js build output is generated CSS; never lint it.
-      ...(stack.nextjs ? { ignoreFiles: ['.next/**', 'out/**', 'node_modules/**'] } : {}),
-    };
-
-    const configPath = path.join(process.cwd(), '.stylelintrc.json');
+    const configPath = path.join(process.cwd(), targetFile);
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 
     process.stdout.write(`\n✓ Wrote ${configPath}\n`);
@@ -229,7 +342,7 @@ async function run() {
   }
 }
 
-module.exports = { AGENT_TARGETS, detect, installAgents, run, selectProfile };
+module.exports = { AGENT_TARGETS, detect, findActiveStylelintConfig, installAgents, run, selectProfile };
 
 if (require.main === module) {
   run();

package/src/cli/quickstart.js

@@ -77,9 +77,16 @@ function topEntries(counts, limit = MAX_LISTED) {
     .slice(0, limit);
 }
 
-function suggestedStylelintConfig({ nextjs = false, profile, tokenFiles }) {
-  const ruleOptions = { scale: 'auto' };
-  if (tokenFiles.length > 0) {
+/**
+ * The config to paste. With a scale inferred from tokens it is `scale: "auto"`
+ * pointed at the same token files, so Stylelint infers what the audit did.
+ * When the audit fell back to its default scale, that scale is written out:
+ * `scale: "auto"` would fall back to the `rhythmic-4` preset instead, which is
+ * a longer scale, and the pasted config would not reproduce this report (#246).
+ */
+function suggestedStylelintConfig({ fallbackScale = null, nextjs = false, profile, tokenFiles }) {
+  const ruleOptions = Array.isArray(fallbackScale) ? { scale: [...fallbackScale] } : { scale: 'auto' };
+  if (!fallbackScale && tokenFiles.length > 0) {
     ruleOptions.scaleSources = tokenFiles.map(toPosix);
   }
   return {
@@ -99,6 +106,9 @@ function eslintSnippet(scaleValues) {
     '',
     'export default [',
     '  {',
+    // Without `files` and JSX parsing, a flat config lints no .jsx at all (#243).
+    "    files: ['**/*.{js,jsx,mjs,cjs}'],",
+    '    languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },',
     "    plugins: { 'rhythmguard-tailwind': rhythmguard },",
     `    rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['warn', { scale: [${scale}] }] },`,
     '  },',
@@ -149,7 +159,9 @@ async function run() {
     return;
   }
 
-  if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0) {
+  const scanned = report.scanned || {};
+  const skippedStylesheets = (scanned.scssSkipped || 0) + (scanned.stylelintIgnored || 0);
+  if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0 && skippedStylesheets === 0) {
     out.push('  No CSS files found here. Run from your project root, or audit a directory directly:');
     out.push('    npx rhythmguard audit ./src', '');
     process.stdout.write(`${out.join('\n')}\n`);
@@ -161,10 +173,10 @@ async function run() {
   out.push(`    Scale           ${scale.values.join(', ')}`);
   out.push(`    Source          ${describeScale(scale)}`);
   if (scale.source === 'fallback' && scale.rejected) {
-    out.push(`    Note            Spacing tokens were found but do not form a scale (${scale.rejected.reasons.join(', ')}); the rhythmic-4 preset is being used.`);
+    out.push(`    Note            Spacing tokens were found but do not form a scale (${scale.rejected.reasons.join(', ')}); the audit's default scale is being used.`);
     out.push('                    Point scaleSources at your real token file, or tighten tokenPattern.');
   } else if (scale.source === 'fallback') {
-    out.push('    Note            No spacing tokens found; the rhythmic-4 preset is being used.');
+    out.push("    Note            No spacing tokens found; the audit's default scale is being used.");
     out.push('                    Add scaleSources or define --space-*/--spacing-* custom properties to lint against your own scale.');
   }
   out.push('');
@@ -173,6 +185,17 @@ async function run() {
   out.push('  Findings');
   out.push(`    CSS files       ${report.cssFilesScanned}`);
   out.push(`    Template files  ${report.templateFilesScanned}`);
+  if (skippedStylesheets > 0) {
+    const reasons = [
+      ...(scanned.scssSkipped > 0 ? [`${scanned.scssSkipped} SCSS without postcss-scss`] : []),
+      ...(scanned.stylelintIgnored > 0 ? [`${scanned.stylelintIgnored} in .stylelintignore`] : []),
+    ];
+    out.push(`    Skipped         ${skippedStylesheets} not audited (${reasons.join(', ')})`);
+  }
+  const parseErrors = (report.findings.parseErrors || []).length;
+  if (parseErrors > 0) {
+    out.push(`    Parse errors    ${parseErrors} not audited (the stylesheet could not be parsed)`);
+  }
   out.push(`    Off-scale       ${offScale.length} in CSS, ${report.findings.tailwind.length} in class strings`);
   out.push(`    Token opps      ${report.findings.css.length - offScale.length} raw values that match or deserve a token`);
   out.push(`    Cleanliness     ${report.scaleCleanliness}%`);
@@ -192,12 +215,15 @@ async function run() {
 
   const profile = stack.tailwind ? 'tailwind' : 'recommended';
   out.push(`  Paste this into .stylelintrc.json${stack.hasExistingConfig ? ' (merge with your existing config)' : ''}:`, '');
-  out.push(JSON.stringify(suggestedStylelintConfig({ nextjs: stack.nextjs, profile, tokenFiles }), null, 2).replace(/^/gm, '    '));
+  const fallbackScale = scale.source === 'fallback' ? scale.values : null;
+  out.push(JSON.stringify(suggestedStylelintConfig({ fallbackScale, nextjs: stack.nextjs, profile, tokenFiles }), null, 2).replace(/^/gm, '    '));
   out.push('');
 
   if (stack.tailwind) {
     out.push('  Tailwind class strings need the ESLint companion. Paste this into eslint.config.js:', '');
     out.push(eslintSnippet(scale.values).replace(/^/gm, '    '));
+    out.push('', '    TypeScript, Vue, Svelte and Astro files need their parser in a block of their own; see the');
+    out.push('    eslint-plugin-rhythmguard README, "Other file types".');
     out.push('');
   }
 
@@ -211,4 +237,4 @@ async function run() {
   process.stdout.write(`${out.join('\n')}\n`);
 }
 
-module.exports = { findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };
+module.exports = { eslintSnippet, findTokenFiles, run, suggestedStylelintConfig, tailwindMajor };

package/src/core/fs-cache.js

@@ -31,6 +31,12 @@ function cachedByFiles(cacheKey, compute) {
   return value;
 }
 
+/** Number of cached entries, for tests that check the cache stays bounded. */
+function cacheSize() {
+  return cache.size;
+}
+
 module.exports = {
+  cacheSize,
   cachedByFiles,
 };

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