stylelint-plugin-rhythmguard 3.4.0 → 3.6.0

package/src/audit/render-markdown.js

@@ -16,6 +16,7 @@ function renderMarkdown(report) {
   const lines = [
     '# Rhythmguard Design-System Audit',
     '',
+    ...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new.`, ''] : []),
     `Directory: \`${report.directory}\``,
     '',
     '## Summary',
@@ -36,6 +37,10 @@ function renderMarkdown(report) {
     lines.push(`| Scale source | ${describeScaleSource(report.scale)} |`);
   }
 
+  if (report.decisions) {
+    lines.push(`| Decisions | ${report.decisions.adopt + report.decisions.allow + report.decisions.snap + report.decisions.undecided} (${report.decisions.adopt} adopt, ${report.decisions.allow} allow, ${report.decisions.snap} snap, ${report.decisions.undecided} undecided); ${report.decisions.suppressed} findings suppressed |`);
+  }
+
   if (report.baseline) {
     lines.push(`| New findings | ${report.baseline.newFindingsCount} |`);
     lines.push(`| Resolved findings | ${report.baseline.resolvedFindingsCount} |`);
@@ -48,6 +53,7 @@ function renderMarkdown(report) {
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
   appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
   appendTokenContractMarkdown(lines, report.tokenContract);
+  appendTokenChainsMarkdown(lines, report.tokenContract.chains);
   appendBaselineMarkdown(lines, report);
 
   if (report.topAffectedFiles.length > 0) {
@@ -86,6 +92,31 @@ function renderMarkdown(report) {
   return `${lines.join('\n')}\n`;
 }
 
+function appendTokenChainsMarkdown(lines, chains) {
+  if (!chains || chains.summary.total === 0) {
+    return;
+  }
+  const { summary } = chains;
+  lines.push('## Token Chains');
+  lines.push('');
+  const attention = ['off-scale', 'unresolved', 'ambiguous', 'computed', 'non-length']
+    .filter((outcome) => summary[outcome] > 0)
+    .map((outcome) => `${summary[outcome]} ${outcome}`);
+  lines.push(`${summary['on-scale']} of ${summary.total} spacing tokens resolve to the scale${attention.length > 0 ? `; ${attention.join(', ')}` : ''}. A token is followed through \`var()\` to its terminal value; the token layer, not the literal, is where a system like this keeps its discipline.`);
+  lines.push('');
+  if (chains.entries.length > 0) {
+    lines.push('| Token | Outcome | Detail |');
+    lines.push('| --- | --- | --- |');
+    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(' → ')}` : ''} |`);
+    }
+    lines.push('');
+  }
+}
+
 function appendTokenContractMarkdown(lines, tokenContract) {
   const {
     conflictingTokens,

package/src/audit/render-text.js

@@ -31,6 +31,12 @@ function renderText(report) {
     const rejected = report.scale.rejected ? ` (${report.scale.rejected.source} rejected: ${report.scale.rejected.reasons.join(', ')})` : '';
     lines.push(`  Scale source             ${report.scale.source}${files}${rejected}`);
   }
+  if (report.decisions) {
+    lines.push(`  Decisions                ${report.decisions.adopt + report.decisions.allow + report.decisions.snap + report.decisions.undecided} (${report.decisions.adopt} adopt, ${report.decisions.allow} allow, ${report.decisions.snap} snap, ${report.decisions.undecided} undecided); ${report.decisions.suppressed} findings suppressed`);
+  }
+  if (report.baseline) {
+    lines.push(`  Since baseline           ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new`);
+  }
   lines.push('');
 
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
@@ -39,6 +45,11 @@ function renderText(report) {
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
   appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
   appendTokenContractText(lines, report.tokenContract);
+  if (report.tokenContract.chains && report.tokenContract.chains.summary.total > 0) {
+    const { summary } = report.tokenContract.chains;
+    lines.push(`  Token chains             ${summary['on-scale']} of ${summary.total} resolve to the scale (${summary['off-scale']} off-scale, ${summary.unresolved} unresolved, ${summary.ambiguous} ambiguous)`);
+    lines.push('');
+  }
   appendBaselineText(lines, report);
 
   if (report.topAffectedFiles.length > 0) {

package/src/audit/report.js

@@ -24,6 +24,8 @@ const {
   inferScaleFromDefinitions,
   scaleFromDefinitions,
 } = require('../core/scale-inference');
+const { applyDecisions, buildDecisionPlan } = require('./decisions');
+const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
 const { assertDirectory, getScanFiles } = require('./scan/files');
 const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
 const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
@@ -62,7 +64,13 @@ async function createAuditReport(options) {
 
   const cssResults = await runStylelintAudit(cssFiles, lintOptions);
   const stylelintFindings = collectCssFindings(cssResults);
-  const cssFindings = stylelintFindings.filter((finding) => !finding.type.startsWith('motion-'));
+  const decided = applyDecisions({
+    baseFontSize: parsed.baseFontSize,
+    cssFindings: stylelintFindings.filter((finding) => !finding.type.startsWith('motion-')),
+    decisions: parsed.decisions || [],
+    tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
+  });
+  const cssFindings = decided.cssFindings;
   const motionFindings = [
     ...stylelintFindings.filter((finding) => finding.type.startsWith('motion-')),
     ...collectTailwindMotionFindings(templateFiles, lintOptions),
@@ -81,7 +89,7 @@ async function createAuditReport(options) {
     scanScope,
     scssFiles: cssResults.scssFiles || 0,
     scssSkipped: cssResults.scssSkipped || 0,
-    tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
+    tailwindFindings: decided.tailwindFindings,
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,
     tokenKind: parsed.tokenKind,
@@ -89,6 +97,26 @@ async function createAuditReport(options) {
     tokenSourceWarnings: tokenSourceResult.warnings,
   });
 
+  report.tokenContract.chains = toChainsContract(resolveTokenChains({
+    baseFontSize: parsed.baseFontSize,
+    declarations: collectDeclarations({
+      cssFiles,
+      externalDefinitions: tokenSourceResult.definitions,
+      skipFile: (file) => NON_AUTHORED_SEGMENT.test(file),
+    }),
+    scale: scale.values,
+  }));
+  report.decisions = decided.summary;
+  report.decisionPlan = buildDecisionPlan({
+    baseFontSize: parsed.baseFontSize,
+    decisions: parsed.decisions || [],
+    offScaleFindings: [
+      ...stylelintFindings.filter((finding) => finding.type === 'off-scale'),
+      ...collectTailwindFindings(templateFiles, lintOptions),
+    ],
+    scale: scale.values,
+  });
+
   if (parsed.sinceBaseline) {
     applyBaselineComparison(report, parsed.baselinePath);
   }

package/src/audit/scan/stylesheets.js

@@ -45,6 +45,7 @@ async function runStylelintAudit(cssFiles, options) {
     'rhythmguard/use-scale': [
       true,
       {
+        decisions: false,
         baseFontSize: options.baseFontSize,
         scale: options.scale,
         severity: 'warning',

package/src/audit/shared.js

@@ -70,6 +70,8 @@ function createDefaultAuditOptions() {
     dir: null,
     failOnNewDrift: false,
     badgeMetric: 'drift',
+    decisions: [],
+    plan: false,
     format: 'text',
     ignorePath: DEFAULT_IGNORE_PATH,
     ignorePatterns: [],

package/src/audit/token-chains.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const fs = require('node:fs');
+const { formatLength, numbersEqual, parseLengthToken, toPx } = require('../core/length');
+const { customPropertyDeclarations, parseTokenValueLength } = require('../core/token-sources');
+const { formatPath } = require('./shared');
+
+/**
+ * Token chains (issue #110). In a token-layered system the SCSS says
+ * `padding: var(--button--padding-x)` and the discipline lives one level up:
+ * does every spacing token resolve to the scale? This follows var() references
+ * through every custom property declaration the audit can see and classifies
+ * each spacing-named token by where its chain ends:
+ *
+ *   on-scale     every terminal is a length on the scale
+ *   off-scale    a terminal is a length off the scale: drift at the token layer
+ *   unresolved   the chain reaches a token nobody declares, or a cycle
+ *   ambiguous    definitions disagree (themes, media queries) on the length
+ *   computed     the value is calc() or otherwise not a plain length or var()
+ *   non-length   the value is not a single length (a shorthand, a keyword)
+ *
+ * A token that is defined several times keeps every definition; the chain
+ * reports the set, never a guess.
+ */
+// `size` counts only as a name prefix (`--size-px--m`, mittwald Flow); anywhere else it is a
+// font size or a dimension (`--account-bio-size`, `--circle-size`), not spacing.
+const SPACING_TOKEN_NAME = /^--size(?:-|$)|(?:^--|-)(?<!letter-)(?<!word-)(?:space|spacing|spacer|padding|margin|gap|inset)(?:-|$)/i;
+const VAR_REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]+))?\)$/;
+const OUTCOMES = ['on-scale', 'off-scale', 'unresolved', 'ambiguous', 'computed', 'non-length'];
+
+function isSpacingTokenName(token) {
+  return token.startsWith('--') && SPACING_TOKEN_NAME.test(token);
+}
+
+/** Every custom property declaration the audit can see: scanned stylesheets plus external token definitions. */
+function collectDeclarations({ cssFiles, externalDefinitions, skipFile = () => false }) {
+  const declarations = new Map();
+  const add = (token, value) => {
+    if (!declarations.has(token)) declarations.set(token, new Set());
+    declarations.get(token).add(String(value).trim());
+  };
+  for (const filePath of cssFiles) {
+    if (skipFile(formatPath(filePath))) continue;
+    let source;
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const declaration of customPropertyDeclarations(source)) add(declaration.token, declaration.value);
+  }
+  for (const definition of (externalDefinitions || new Map()).values()) {
+    if (!definition.token.startsWith('--')) continue;
+    for (const value of definition.values) add(definition.token, value);
+  }
+  return declarations;
+}
+
+function resolveTokenChains({ baseFontSize = 16, declarations, scale }) {
+  const scalePx = (scale || []).map(Number).filter(Number.isFinite);
+  const memo = new Map();
+
+  const classifyValue = (raw, stack, via) => {
+    const value = String(raw).trim();
+    const length = parseTokenValueLength(value) || parseLengthToken(value);
+    if (length && !/^var\(/i.test(value)) {
+      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)) {
+        via.push(target);
+        return resolve(target, stack);
+      }
+      if (fallback !== undefined) {
+        return classifyValue(fallback, stack, via);
+      }
+      return { outcomes: ['unresolved'], reason: `\`${target}\` is not declared`, terminals: [] };
+    }
+    if (/var\(|calc\(|clamp\(|min\(|max\(/i.test(value)) {
+      return { outcomes: ['computed'], terminals: [] };
+    }
+    return { outcomes: ['non-length'], terminals: [] };
+  };
+
+  const resolve = (token, stack) => {
+    if (memo.has(token)) return memo.get(token);
+    if (stack.includes(token)) {
+      return { outcomes: ['unresolved'], reason: `cycle through \`${stack[stack.length - 1]}\``, terminals: [], via: [] };
+    }
+    const values = declarations.get(token);
+    if (!values) return { outcomes: ['unresolved'], reason: `\`${token}\` is not declared`, terminals: [], via: [] };
+    const nextStack = [...stack, token];
+    const outcomes = new Set();
+    const terminals = new Set();
+    const via = [];
+    let reason = null;
+    for (const raw of values) {
+      const result = classifyValue(raw, nextStack, via);
+      for (const outcome of result.outcomes) outcomes.add(outcome);
+      for (const terminal of result.terminals) terminals.add(terminal);
+      if (result.reason && !reason) reason = result.reason;
+      if (result.via) via.push(...result.via.filter((name) => !via.includes(name)));
+    }
+    const result = { outcomes: [...outcomes], reason, terminals: [...terminals], via };
+    memo.set(token, result);
+    return result;
+  };
+
+  const onScale = (terminal) => {
+    const parsed = parseLengthToken(terminal);
+    return parsed && scalePx.some((step) => numbersEqual(step, parsed.number));
+  };
+
+  const entries = [];
+  for (const token of [...declarations.keys()].sort()) {
+    if (!isSpacingTokenName(token)) continue;
+    const result = resolve(token, []);
+    let outcome;
+    if (result.outcomes.includes('unresolved')) outcome = 'unresolved';
+    else if (result.outcomes.includes('computed')) outcome = 'computed';
+    else if (result.outcomes.includes('non-length')) outcome = 'non-length';
+    else if (result.terminals.length > 1) outcome = 'ambiguous';
+    else if (result.terminals.length === 1) outcome = onScale(result.terminals[0]) ? 'on-scale' : 'off-scale';
+    else outcome = 'unresolved';
+    entries.push({ outcome, reason: result.reason || null, terminals: result.terminals, token, via: result.via });
+  }
+
+  const summary = Object.fromEntries([['total', entries.length], ...OUTCOMES.map((outcome) => [outcome, 0])]);
+  for (const entry of entries) summary[entry.outcome] += 1;
+  return { entries, summary };
+}
+
+/** The contract shape: counts for everything, entries only for what needs attention. */
+function toChainsContract(chains) {
+  const attention = new Set(['off-scale', 'unresolved', 'ambiguous']);
+  return {
+    entries: chains.entries.filter((entry) => attention.has(entry.outcome)).map((entry) => ({
+      outcome: entry.outcome,
+      ...(entry.reason ? { reason: entry.reason } : {}),
+      terminals: entry.terminals,
+      token: entry.token,
+      via: entry.via,
+    })),
+    summary: chains.summary,
+  };
+}
+
+module.exports = {
+  OUTCOMES,
+  collectDeclarations,
+  isSpacingTokenName,
+  resolveTokenChains,
+  toChainsContract,
+};

package/src/cli/audit.js

@@ -48,6 +48,11 @@ async function run() {
     process.exit(1);
   }
 
+  if (parsed.plan) {
+    writeOutput(`${JSON.stringify({ decisions: report.decisionPlan }, null, 2)}\n`, parsed.outputPath);
+    return;
+  }
+
   const auditFailures = getAuditFailures(report, parsed);
 
   if (parsed.format === 'json') {

package/src/cli/fix.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const { loadRcDecisions } = require('../core/decisions');
+const { parseLengthToken, toPx } = require('../core/length');
+const { runCodemod } = require('../audit/codemod');
+
+const HELP = `Usage: rhythmguard fix <dir> --value <length> --to <replacement> [options]
+       rhythmguard fix <dir> --decided [options]
+
+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.
+
+Options:
+  --value <length>       The literal to replace, for example 10px or 0.625rem
+  --to <replacement>     What to write, for example var(--space-sm) or 8px
+  --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)
+  --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 };
+  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;
+    else if (arg === '--write') parsed.write = true;
+    else if (arg === '--decided') parsed.decided = true;
+    else if (arg === '--value') parsed.value = next();
+    else if (arg.startsWith('--value=')) parsed.value = arg.slice('--value='.length);
+    else if (arg === '--to') parsed.replacement = next();
+    else if (arg.startsWith('--to=')) parsed.replacement = arg.slice('--to='.length);
+    else if (arg === '--properties') parsed.properties = splitList(next());
+    else if (arg.startsWith('--properties=')) parsed.properties = splitList(arg.slice('--properties='.length));
+    else if (arg === '--base-font-size') parsed.baseFontSize = Number(next());
+    else if (arg.startsWith('--base-font-size=')) parsed.baseFontSize = Number(arg.slice('--base-font-size='.length));
+    else if (!arg.startsWith('-') && !parsed.dir) parsed.dir = arg;
+    else throw new Error(`Unknown option: ${arg}`);
+  }
+  if (!Number.isFinite(parsed.baseFontSize) || parsed.baseFontSize <= 0) {
+    throw new Error('--base-font-size must be a positive number.');
+  }
+  return parsed;
+}
+
+function splitList(raw) {
+  return String(raw || '').split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function lengthToPx(value, baseFontSize) {
+  const parsed = typeof value === 'string' ? parseLengthToken(value.trim()) : null;
+  const px = parsed ? toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize) : null;
+  if (px === null || !Number.isFinite(px) || px === 0) {
+    throw new Error(`--value must be a CSS length such as 10px or 0.625rem, got ${JSON.stringify(value)}.`);
+  }
+  return px;
+}
+
+/** The replacements to run: one from --value/--to, or every snap decision with a "to". */
+function plannedReplacements(parsed) {
+  if (parsed.decided) {
+    const decisions = loadRcDecisions(process.cwd(), { baseFontSize: parsed.baseFontSize });
+    const snaps = decisions.filter((decision) => decision.decision === 'snap');
+    return {
+      replacements: snaps.filter((decision) => decision.to).map((decision) => ({ label: decision.value, px: decision.px, replacement: decision.to })),
+      skippedSnaps: snaps.filter((decision) => !decision.to).map((decision) => decision.value),
+    };
+  }
+  if (!parsed.value) {
+    throw new Error('Pass --value <length> and --to <replacement>, or --decided.');
+  }
+  if (!parsed.replacement) {
+    throw new Error('--to <replacement> is required with --value.');
+  }
+  return { replacements: [{ label: parsed.value, px: lengthToPx(parsed.value, parsed.baseFontSize), replacement: parsed.replacement }], skippedSnaps: [] };
+}
+
+function run() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(3));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${HELP}`);
+    process.exit(1);
+  }
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (!parsed.dir) {
+    process.stderr.write(`Pass the directory to rewrite.\n\n${HELP}`);
+    process.exit(1);
+  }
+
+  let plan;
+  try {
+    plan = plannedReplacements(parsed);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+
+  const lines = [];
+  let total = 0;
+  const touched = new Set();
+  const skipped = [];
+  for (const replacement of plan.replacements) {
+    const outcome = runCodemod({
+      baseFontSize: parsed.baseFontSize,
+      dir: parsed.dir,
+      properties: parsed.properties,
+      px: replacement.px,
+      replacement: replacement.replacement,
+      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}`);
+      }
+    }
+    skipped.push(...outcome.skipped);
+  }
+
+  if (lines.length > 0) {
+    lines.push('');
+  }
+  const noun = total === 1 ? 'replacement' : 'replacements';
+  const files = touched.size === 1 ? 'file' : 'files';
+  lines.push(`${total} ${noun} in ${touched.size} ${files}${parsed.write ? '' : ' (dry run; pass --write to apply)'}`);
+  if (plan.skippedSnaps.length > 0) {
+    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) {
+    lines.push(`skipped ${entry.file}: ${entry.reason}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+module.exports = { HELP, parseArgs, run };
+
+if (require.main === module) {
+  run();
+}

package/src/cli/index.js

@@ -11,6 +11,7 @@ the spacing scale, audits the current directory and prints a config to paste.
 Commands:
   quickstart    Same as running with no command
   audit <dir>   Report design-system drift across CSS and Tailwind class strings
+  fix <dir>     Replace one off-scale value everywhere, or execute snap decisions
   init          Scaffold a Rhythmguard config for your project
                 --agents <claude|cursor|copilot|all> installs the agent instruction packs instead
   doctor        Validate your Rhythmguard setup
@@ -22,6 +23,7 @@ Examples:
   npx rhythmguard
   npx rhythmguard audit ./src
   npx rhythmguard audit ./src --format markdown
+  npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write
   npx rhythmguard init
   npx rhythmguard init --agents all
   npx rhythmguard doctor
@@ -36,6 +38,8 @@ if (!command || command === 'quickstart') {
   require('./quickstart').run();
 } else if (command === 'audit') {
   require('./audit').run();
+} else if (command === 'fix') {
+  require('./fix').run();
 } else if (command === 'init') {
   require('./init').run();
 } else if (command === 'doctor') {

package/src/core/decisions.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { cachedByFiles } = require('./fs-cache');
+const { numbersEqual, parseLengthToken, toPx } = require('./length');
+
+/**
+ * The `decisions` section of .rhythmguardrc.json records what a team decided
+ * about each off-scale value the audit found:
+ *
+ *   adopt      the value is part of the scale (optionally naming the token it
+ *              should become); it stops being a finding everywhere
+ *   allow      the value is intentional and not rhythm (borders, focus rings);
+ *              not a finding, optionally only on some properties
+ *   snap       the value is a slip; still a finding, and `rhythmguard fix
+ *              --decided` executes it when `to` names the replacement
+ *   undecided  recorded, still a finding, counted so the team sees it
+ *
+ * Decisions are matched by px value, so `10px` and `0.625rem` are one
+ * decision. The Stylelint rules and the audit read the same file, so a
+ * decision made once holds in the editor, in CI and in the report.
+ */
+const RC_FILE = '.rhythmguardrc.json';
+const DECISIONS = new Set(['adopt', 'allow', 'snap', 'undecided']);
+
+function normalizeDecisions(raw, { baseFontSize = 16 } = {}) {
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error('Invalid Rhythmguard config: decisions must be an array.');
+  }
+  return raw.map((entry, index) => normalizeDecision(entry, index, baseFontSize));
+}
+
+function normalizeDecision(entry, index, baseFontSize) {
+  const where = `decisions[${index}]`;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`Invalid Rhythmguard config: ${where} must be an object.`);
+  }
+  const parsed = typeof entry.value === 'string' ? parseLengthToken(entry.value.trim()) : null;
+  const px = parsed ? toPx(Math.abs(parsed.number), parsed.unit || 'px', baseFontSize) : null;
+  if (px === null || !Number.isFinite(px)) {
+    throw new Error(`Invalid Rhythmguard config: ${where}.value must be a CSS length such as "10px" or "0.75rem".`);
+  }
+  if (!DECISIONS.has(entry.decision)) {
+    throw new Error(`Invalid Rhythmguard config: ${where}.decision must be one of ${Array.from(DECISIONS).join(', ')}.`);
+  }
+  if (entry.properties !== undefined && (!Array.isArray(entry.properties) || !entry.properties.every((p) => typeof p === 'string' && p.trim()))) {
+    throw new Error(`Invalid Rhythmguard config: ${where}.properties must be an array of property names or patterns such as "border-*".`);
+  }
+  if (entry.as !== undefined && (typeof entry.as !== 'string' || !/^(?:--|\$)[\w-]+$/.test(entry.as))) {
+    throw new Error(`Invalid Rhythmguard config: ${where}.as must be a custom property or Sass variable name such as "--space-2".`);
+  }
+  if (entry.to !== undefined && (typeof entry.to !== 'string' || !entry.to.trim())) {
+    throw new Error(`Invalid Rhythmguard config: ${where}.to must be the replacement text a snap writes, such as "8px" or "var(--space-2)".`);
+  }
+  if (entry.reason !== undefined && typeof entry.reason !== 'string') {
+    throw new Error(`Invalid Rhythmguard config: ${where}.reason must be a string.`);
+  }
+  return {
+    as: entry.as || null,
+    decision: entry.decision,
+    properties: entry.properties ? entry.properties.map((p) => p.trim().toLowerCase()) : null,
+    px,
+    reason: entry.reason || null,
+    to: entry.to ? entry.to.trim() : null,
+    value: entry.value.trim(),
+  };
+}
+
+function propertyMatchesPattern(prop, pattern) {
+  if (pattern.endsWith('*')) {
+    return prop.startsWith(pattern.slice(0, -1));
+  }
+  return prop === pattern;
+}
+
+/** The decision that applies to a value (in px) on a property, or null. */
+function decisionFor(px, prop, decisions) {
+  if (!decisions || decisions.length === 0) {
+    return null;
+  }
+  const normalizedProp = String(prop || '').toLowerCase();
+  for (const decision of decisions) {
+    if (!numbersEqual(decision.px, Math.abs(px))) {
+      continue;
+    }
+    if (decision.properties && !decision.properties.some((pattern) => propertyMatchesPattern(normalizedProp, pattern))) {
+      continue;
+    }
+    return decision;
+  }
+  return null;
+}
+
+/** Decisions from the .rhythmguardrc.json in cwd, cached and revalidated by mtime. Invalid entries throw. */
+function loadRcDecisions(cwd = process.cwd(), { baseFontSize = 16 } = {}) {
+  const rcPath = path.join(cwd, RC_FILE);
+  return cachedByFiles(`decisions:${rcPath}:${baseFontSize}`, (consult) => {
+    consult(rcPath);
+    if (!fs.existsSync(rcPath)) {
+      return [];
+    }
+    let config;
+    try {
+      config = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
+    } catch {
+      return [];
+    }
+    return normalizeDecisions(config && typeof config === 'object' ? config.decisions : undefined, { baseFontSize });
+  });
+}
+
+module.exports = {
+  DECISIONS,
+  decisionFor,
+  loadRcDecisions,
+  normalizeDecisions,
+};

package/src/core/fs-cache.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const fs = require('node:fs');
+
+/**
+ * Editors and pre-commit hooks lint one file at a time, and each lint asks the
+ * filesystem the same questions: which package.json files sit between cwd and
+ * the repository, what .rhythmguardrc.json says, whether a token package is
+ * installed. The answers change only when one of those files changes, so a
+ * result is cached per key and revalidated by the mtime of every file the
+ * computation consulted: a stat per file instead of a read, a parse and a walk.
+ */
+const cache = new Map();
+
+function fileStamp(file) {
+  try {
+    return fs.statSync(file).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function cachedByFiles(cacheKey, compute) {
+  const cached = cache.get(cacheKey);
+  if (cached && cached.stamps.every(([file, stamp]) => fileStamp(file) === stamp)) {
+    return cached.value;
+  }
+  const consulted = [];
+  const value = compute((file) => consulted.push([file, fileStamp(file)]));
+  cache.set(cacheKey, { stamps: consulted, value });
+  return value;
+}
+
+module.exports = {
+  cachedByFiles,
+};