stylelint-plugin-rhythmguard 1.9.0 → 2.0.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-05-23
+
+### Changed
+
+- `rhythmguard audit --format json` now emits the stable audit contract with `schemaVersion: "2.0"`.
+- Moved the pre-2.0 audit JSON shape to `--format json-v1` for migration compatibility.
+- Updated audit defaults to use the explicit spacing token pattern `^--(space|spacing)-`.
+
+### Added
+
+- Added `stylelint-plugin-rhythmguard/audit` with `createAuditReport`, `loadAuditConfig`, `parseTokenSources`, and `toAuditContractReport`.
+- Added `rhythmguard audit --format html`, `--output <file>`, and `--schema`.
+- Added `rhythmguard doctor` checks for `.rhythmguardrc.json`, configured token sources, motion audit config, and baseline files.
+- Added `docs/MIGRATING_TO_2.md`.
+
 ## [1.9.0] - 2026-05-23
 
 ### Added

package/README.md

@@ -97,9 +97,11 @@ npx rhythmguard audit ./src --staged --max-findings 0
 npx rhythmguard audit ./src --token-source ./tokens.json
 npx rhythmguard audit ./src --token-source ./theme.css --token-source-format css
 npx rhythmguard audit ./src --include-motion
+npx rhythmguard audit ./src --format html --output rhythmguard-report.html
+npx rhythmguard audit --schema
 ```
 
-The report covers authored CSS declarations, Tailwind arbitrary spacing values in common template/source files, and token-contract drift such as missing spacing tokens, unused spacing tokens, repeated raw values that deserve token review, raw values that match known tokens, and conflicting token values. Scan paths are scoped to the directory argument. Use `--ignore`, `.rhythmguardignore`, or `--ignore-path` for generated or legacy subtrees, then add baselines and CI thresholds when you are ready to gate new drift. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
+The report covers authored CSS declarations, Tailwind arbitrary spacing values in common template/source files, and token-contract drift such as missing spacing tokens, unused spacing tokens, repeated raw values that deserve token review, raw values that match known tokens, conflicting token values, and opt-in motion rhythm drift. Scan paths are scoped to the directory argument. Use `--ignore`, `.rhythmguardignore`, or `--ignore-path` for generated or legacy subtrees, then add baselines and CI thresholds when you are ready to gate new drift. Markdown output is PR-ready for UX developers, UX designers, and design-system owners:
 
 ```md
 # Rhythmguard Design-System Audit
@@ -136,6 +138,44 @@ For large codebases, put shared audit settings in `.rhythmguardrc.json`:
 
 `rhythmguard audit` loads `.rhythmguardrc.json` automatically when present. Use `--config <file>` for another config, `--no-config` to skip config discovery, and `--token-source <file>` for extra canonical token files. Token source paths in config files resolve from the config file directory; CLI token source paths resolve from the current working directory. Supported source formats are CSS custom properties and Tailwind v4 `@theme`, flat JSON maps, Style Dictionary JSON, and DTCG JSON.
 
+### Audit JSON 2.0 and API
+
+In Rhythmguard 2.0, `--format json` emits the stable audit contract:
+
+```json
+{
+  "schemaVersion": "2.0",
+  "command": { "directory": "./src", "scanScope": "full" },
+  "summary": { "totalFindings": 12, "scaleCleanliness": 94 },
+  "scanned": { "cssFiles": 10, "templateFiles": 20 },
+  "contracts": {
+    "scale": {},
+    "tokens": {},
+    "motion": {}
+  },
+  "findings": {
+    "css": [],
+    "tailwind": [],
+    "motion": []
+  },
+  "baseline": null
+}
+```
+
+Use `--format json-v1` for the pre-2.0 JSON shape during migration.
+
+Programmatic usage:
+
+```js
+const {
+  createAuditReport,
+  toAuditContractReport,
+} = require('stylelint-plugin-rhythmguard/audit');
+
+const report = await createAuditReport({ dir: './src', noConfig: true });
+const contract = toAuditContractReport(report);
+```
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -61,6 +61,10 @@
       "require": "./src/presets/index.js",
       "import": "./src/presets/index.mjs"
     },
+    "./audit": {
+      "require": "./src/audit/index.js",
+      "import": "./src/audit/index.mjs"
+    },
     "./rules/use-scale": {
       "require": "./src/rules/use-scale/index.js",
       "import": "./src/rules/use-scale/index.mjs"

package/src/audit/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const {
+  AUDIT_JSON_SCHEMA,
+  createAuditReport,
+  loadAuditConfig,
+  toAuditContractReport,
+} = require('../cli/audit');
+const { parseTokenSources } = require('../utils/token-sources');
+
+module.exports = {
+  AUDIT_JSON_SCHEMA,
+  createAuditReport,
+  loadAuditConfig,
+  parseTokenSources,
+  toAuditContractReport,
+};

package/src/audit/index.mjs

@@ -0,0 +1,11 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const audit = require('./index.js');
+
+export default audit;
+export const AUDIT_JSON_SCHEMA = audit.AUDIT_JSON_SCHEMA;
+export const createAuditReport = audit.createAuditReport;
+export const loadAuditConfig = audit.loadAuditConfig;
+export const parseTokenSources = audit.parseTokenSources;
+export const toAuditContractReport = audit.toAuditContractReport;

package/src/cli/audit.js

@@ -25,8 +25,9 @@ const DEFAULT_BASE_FONT_SIZE = 16;
 const DEFAULT_BASELINE_PATH = '.rhythmguard-baseline.json';
 const DEFAULT_CONFIG_PATH = '.rhythmguardrc.json';
 const DEFAULT_IGNORE_PATH = '.rhythmguardignore';
+const DEFAULT_AUDIT_TOKEN_PATTERN = '^--(space|spacing)-';
 const DEFAULT_TOKEN_CANDIDATE_MIN_COUNT = 2;
-const VALID_FORMATS = new Set(['text', 'json', 'markdown']);
+const VALID_FORMATS = new Set(['text', 'json', 'json-v1', 'markdown', 'html']);
 const SKIP_DIRS = new Set([
   '.git',
   '.next',
@@ -56,9 +57,11 @@ const TEMPLATE_EXTENSIONS = new Set([
 const HELP = `Usage: rhythmguard audit <dir> [options]
 
 Options:
-  --format <text|json|markdown>  Output format (default: text)
+  --format <text|json|json-v1|markdown|html> Output format (default: text)
   --json                         Alias for --format json
   --markdown                     Alias for --format markdown
+  --schema                       Print the audit JSON schema and exit
+  --output <file>                Write json, markdown, or html output to a file
   --config <file>                Load audit config (default: .rhythmguardrc.json when present)
   --no-config                    Ignore .rhythmguardrc.json discovery
   --ignore <pattern>             Exclude root-relative path/glob (repeatable, comma-separated)
@@ -81,31 +84,7 @@ Options:
 `;
 
 function parseArgs(argv) {
-  const parsed = {
-    baselinePath: DEFAULT_BASELINE_PATH,
-    baseFontSize: DEFAULT_BASE_FONT_SIZE,
-    cliOptions: new Set(),
-    configExplicit: false,
-    configPath: DEFAULT_CONFIG_PATH,
-    dir: null,
-    failOnNewDrift: false,
-    format: 'text',
-    ignorePath: DEFAULT_IGNORE_PATH,
-    ignorePatterns: [],
-    includeMotion: false,
-    maxFindings: null,
-    minCleanliness: null,
-    noConfig: false,
-    scale: DEFAULT_SCALE,
-    since: null,
-    sinceBaseline: false,
-    staged: false,
-    tokenCandidateMinCount: DEFAULT_TOKEN_CANDIDATE_MIN_COUNT,
-    tokenKind: 'spacing',
-    tokenSourceFormat: 'auto',
-    tokenSources: [],
-    writeBaseline: false,
-  };
+  const parsed = createDefaultAuditOptions();
 
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
@@ -115,6 +94,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--schema') {
+      parsed.schema = true;
+      parsed.format = 'json';
+      continue;
+    }
+
     if (arg === '--json') {
       parsed.format = 'json';
       continue;
@@ -125,6 +110,18 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--output') {
+      parsed.outputPath = parsePathOption(argv[++index], '--output');
+      parsed.cliOptions.add('outputPath');
+      continue;
+    }
+
+    if (arg.startsWith('--output=')) {
+      parsed.outputPath = parsePathOption(arg.slice('--output='.length), '--output');
+      parsed.cliOptions.add('outputPath');
+      continue;
+    }
+
     if (arg === '--ignore') {
       parsed.ignorePatterns.push(...parseIgnorePatterns(argv[++index]));
       parsed.cliOptions.add('ignore');
@@ -365,7 +362,7 @@ function parseArgs(argv) {
   }
 
   if (!VALID_FORMATS.has(parsed.format)) {
-    throw new Error(`Invalid format "${parsed.format}". Expected text, json, or markdown.`);
+    throw new Error(`Invalid format "${parsed.format}". Expected text, json, json-v1, markdown, or html.`);
   }
 
   if (parsed.since && parsed.staged) {
@@ -379,6 +376,36 @@ function parseArgs(argv) {
   return parsed;
 }
 
+function createDefaultAuditOptions() {
+  return {
+    baselinePath: DEFAULT_BASELINE_PATH,
+    baseFontSize: DEFAULT_BASE_FONT_SIZE,
+    cliOptions: new Set(),
+    configExplicit: false,
+    configPath: DEFAULT_CONFIG_PATH,
+    dir: null,
+    failOnNewDrift: false,
+    format: 'text',
+    ignorePath: DEFAULT_IGNORE_PATH,
+    ignorePatterns: [],
+    includeMotion: false,
+    maxFindings: null,
+    minCleanliness: null,
+    noConfig: false,
+    outputPath: null,
+    scale: DEFAULT_SCALE,
+    schema: false,
+    since: null,
+    sinceBaseline: false,
+    staged: false,
+    tokenCandidateMinCount: DEFAULT_TOKEN_CANDIDATE_MIN_COUNT,
+    tokenKind: 'spacing',
+    tokenSourceFormat: 'auto',
+    tokenSources: [],
+    writeBaseline: false,
+  };
+}
+
 function parsePathOption(raw, optionName) {
   if (!raw) {
     throw new Error(`Missing value for ${optionName}.`);
@@ -486,25 +513,27 @@ function parseBaseFontSize(raw) {
 
 function assertDirectory(dir) {
   if (!dir) {
-    process.stderr.write(HELP);
-    process.exit(1);
+    throw new Error('Missing audit directory.');
   }
 
   const resolvedDir = path.resolve(dir);
   if (!fs.existsSync(resolvedDir)) {
-    process.stderr.write(`Directory not found: ${dir}\n`);
-    process.exit(1);
+    throw new Error(`Directory not found: ${dir}`);
   }
 
   if (!fs.statSync(resolvedDir).isDirectory()) {
-    process.stderr.write(`Not a directory: ${dir}\n`);
-    process.exit(1);
+    throw new Error(`Not a directory: ${dir}`);
   }
 
   return resolvedDir;
 }
 
 function loadAuditConfig(parsed) {
+  parsed = {
+    ...createDefaultAuditOptions(),
+    ...parsed,
+  };
+
   if (parsed.noConfig) {
     return null;
   }
@@ -901,7 +930,7 @@ async function runStylelintAudit(cssFiles, options) {
         scale: options.scale,
         severity: 'warning',
         tokenMapFromCssCustomProperties: true,
-        tokenPattern: '^--spac(e|ing)-',
+        tokenPattern: DEFAULT_AUDIT_TOKEN_PATTERN,
       },
     ],
   };
@@ -1985,61 +2014,25 @@ function formatPath(filePath) {
   return path.relative(process.cwd(), filePath).replace(/\\/g, '/');
 }
 
-async function run() {
-  let parsed;
-  try {
-    parsed = parseArgs(args);
-  } catch (err) {
-    process.stderr.write(`${err.message}\n\n${HELP}`);
-    process.exit(1);
-  }
-
-  if (parsed.help) {
-    process.stdout.write(HELP);
-    return;
-  }
-
-  try {
-    parsed = applyAuditConfig(parsed, loadAuditConfig(parsed));
-  } catch (err) {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-  }
-
+async function createAuditReport(options) {
+  const parsed = normalizeCreateAuditOptions(options);
   const resolvedDir = assertDirectory(parsed.dir);
   let ignorePatterns;
-  try {
-    ignorePatterns = [
-      ...loadIgnorePatterns(parsed.ignorePath),
-      ...parsed.ignorePatterns,
-    ];
-  } catch (err) {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-  }
+  ignorePatterns = [
+    ...loadIgnorePatterns(parsed.ignorePath),
+    ...parsed.ignorePatterns,
+  ];
 
-  let scanFiles;
-  try {
-    scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
-  } catch (err) {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-  }
+  const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
 
   const { cssFiles, scanScope, templateFiles } = scanFiles;
-  const options = {
+  const lintOptions = {
     baseFontSize: parsed.baseFontSize,
     includeMotion: parsed.includeMotion,
     scale: parsed.scale,
   };
 
-  let cssResults;
-  try {
-    cssResults = await runStylelintAudit(cssFiles, options);
-  } catch (err) {
-    process.stderr.write(`Lint error: ${err.message}\n`);
-    process.exit(1);
-  }
+  const cssResults = await runStylelintAudit(cssFiles, lintOptions);
 
   const tokenSourceResult = parseTokenSources({
     baseFontSize: parsed.baseFontSize,
@@ -2050,7 +2043,7 @@ async function run() {
   const cssFindings = stylelintFindings.filter((finding) => !finding.type.startsWith('motion-'));
   const motionFindings = [
     ...stylelintFindings.filter((finding) => finding.type.startsWith('motion-')),
-    ...collectTailwindMotionFindings(templateFiles, options),
+    ...collectTailwindMotionFindings(templateFiles, lintOptions),
   ];
 
   const report = buildReport({
@@ -2063,7 +2056,7 @@ async function run() {
     includeMotion: parsed.includeMotion,
     motionFindings,
     scanScope,
-    tailwindFindings: collectTailwindFindings(templateFiles, options),
+    tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,
     tokenKind: parsed.tokenKind,
@@ -2071,14 +2064,181 @@ async function run() {
     tokenSourceWarnings: tokenSourceResult.warnings,
   });
 
+  if (parsed.sinceBaseline) {
+    applyBaselineComparison(report, parsed.baselinePath);
+  }
+
+  if (parsed.writeBaseline) {
+    writeBaseline(report, parsed.baselinePath);
+  }
+
+  return report;
+}
+
+function normalizeCreateAuditOptions(options = {}) {
+  const parsed = {
+    ...createDefaultAuditOptions(),
+    ...options,
+    cliOptions: options.cliOptions instanceof Set
+      ? options.cliOptions
+      : new Set(Object.keys(options)),
+  };
+
+  if (!Array.isArray(parsed.ignorePatterns)) {
+    parsed.ignorePatterns = [];
+  }
+
+  if (!Array.isArray(parsed.tokenSources)) {
+    parsed.tokenSources = [];
+  }
+
+  if (parsed.configApplied) {
+    delete parsed.cliOptions;
+    return parsed;
+  }
+
+  return applyAuditConfig(parsed, loadAuditConfig(parsed));
+}
+
+function toAuditContractReport(report) {
+  return {
+    baseline: report.baseline || null,
+    command: {
+      config: report.config,
+      directory: report.directory,
+      scanScope: report.scanScope.mode,
+    },
+    contracts: {
+      motion: report.motion,
+      scale: {
+        cleanliness: report.scaleCleanliness,
+        offScaleValues: report.offScaleValues,
+        tokenOpportunities: report.tokenOpportunities,
+      },
+      tokens: report.tokenContract,
+    },
+    findings: report.findings,
+    scanned: report.scanned,
+    schemaVersion: '2.0',
+    summary: report.summary,
+  };
+}
+
+const AUDIT_JSON_SCHEMA = Object.freeze({
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  additionalProperties: true,
+  properties: {
+    baseline: { type: ['object', 'null'] },
+    command: { type: 'object' },
+    contracts: { type: 'object' },
+    findings: { type: 'object' },
+    scanned: { type: 'object' },
+    schemaVersion: { const: '2.0' },
+    summary: { type: 'object' },
+  },
+  required: ['schemaVersion', 'command', 'summary', 'scanned', 'contracts', 'findings'],
+  title: 'Rhythmguard Audit Report',
+  type: 'object',
+});
+
+function renderHtml(report) {
+  const contractReport = toAuditContractReport(report);
+  const lines = [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<title>Rhythmguard Design-System Audit</title>',
+    '<style>',
+    'body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;margin:0;color:#171717;background:#fafafa;}',
+    'main{max-width:1040px;margin:0 auto;padding:32px 20px;}',
+    'h1,h2{line-height:1.2;}',
+    '.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;}',
+    '.metric{border:1px solid #ddd;background:#fff;padding:14px;border-radius:6px;}',
+    '.metric strong{display:block;font-size:28px;}',
+    'table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #ddd;}',
+    'th,td{padding:10px;border-bottom:1px solid #eee;text-align:left;}',
+    'code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;}',
+    '</style>',
+    '</head>',
+    '<body>',
+    '<main>',
+    '<h1>Rhythmguard Design-System Audit</h1>',
+    `<p>Directory: <code>${escapeHtml(contractReport.command.directory)}</code></p>`,
+    '<section class="grid">',
+    metricHtml('Total findings', report.totalWarnings),
+    metricHtml('Scale cleanliness', `${report.scaleCleanliness}%`),
+    metricHtml('CSS files', report.cssFilesScanned),
+    metricHtml('Template files', report.templateFilesScanned),
+    '</section>',
+    renderHtmlTable('Top Affected Files', ['File', 'Findings'], report.topAffectedFiles.map(({ file, count }) => [file, count])),
+    renderHtmlTable('Token Contract Sources', ['File', 'Format', 'Tokens'], report.tokenContract.sources.map((source) => [
+      source.file,
+      source.format,
+      source.tokenCount,
+    ])),
+    renderHtmlTable('Motion Rhythm Drift', ['Value', 'Count'], Object.entries(report.motion.values)),
+    '<h2>Machine JSON</h2>',
+    `<pre><code>${escapeHtml(JSON.stringify(contractReport, null, 2))}</code></pre>`,
+    '</main>',
+    '</body>',
+    '</html>',
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
+function metricHtml(label, value) {
+  return `<div class="metric"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></div>`;
+}
+
+function renderHtmlTable(title, headers, rows) {
+  if (rows.length === 0) {
+    return '';
+  }
+
+  return [
+    `<h2>${escapeHtml(title)}</h2>`,
+    '<table>',
+    `<thead><tr>${headers.map((header) => `<th>${escapeHtml(header)}</th>`).join('')}</tr></thead>`,
+    '<tbody>',
+    ...rows.map((row) => `<tr>${row.map((cell) => `<td><code>${escapeHtml(cell)}</code></td>`).join('')}</tr>`),
+    '</tbody>',
+    '</table>',
+  ].join('\n');
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+async function run() {
+  let parsed;
   try {
-    if (parsed.sinceBaseline) {
-      applyBaselineComparison(report, parsed.baselinePath);
-    }
+    parsed = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${HELP}`);
+    process.exit(1);
+  }
 
-    if (parsed.writeBaseline) {
-      writeBaseline(report, parsed.baselinePath);
-    }
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  if (parsed.schema) {
+    writeOutput(`${JSON.stringify(AUDIT_JSON_SCHEMA, null, 2)}\n`, parsed.outputPath);
+    return;
+  }
+
+  let report;
+  try {
+    report = await createAuditReport(parsed);
   } catch (err) {
     process.stderr.write(`${err.message}\n`);
     process.exit(1);
@@ -2087,21 +2247,44 @@ async function run() {
   const auditFailures = getAuditFailures(report, parsed);
 
   if (parsed.format === 'json') {
-    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    writeOutput(`${JSON.stringify(toAuditContractReport(report), null, 2)}\n`, parsed.outputPath);
+    finish(auditFailures);
+    return;
+  }
+
+  if (parsed.format === 'json-v1') {
+    writeOutput(`${JSON.stringify(report, null, 2)}\n`, parsed.outputPath);
     finish(auditFailures);
     return;
   }
 
   if (parsed.format === 'markdown') {
-    process.stdout.write(renderMarkdown(report));
+    writeOutput(renderMarkdown(report), parsed.outputPath);
+    finish(auditFailures);
+    return;
+  }
+
+  if (parsed.format === 'html') {
+    writeOutput(renderHtml(report), parsed.outputPath);
     finish(auditFailures);
     return;
   }
 
-  process.stdout.write(renderText(report));
+  writeOutput(renderText(report), parsed.outputPath);
   finish(auditFailures);
 }
 
+function writeOutput(output, outputPath) {
+  if (!outputPath) {
+    process.stdout.write(output);
+    return;
+  }
+
+  const resolvedPath = path.resolve(process.cwd(), outputPath);
+  fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+  fs.writeFileSync(resolvedPath, output);
+}
+
 function finish(auditFailures) {
   if (auditFailures.length === 0) {
     return;
@@ -2111,4 +2294,16 @@ function finish(auditFailures) {
   process.exitCode = 1;
 }
 
-run();
+module.exports = {
+  AUDIT_JSON_SCHEMA,
+  createAuditReport,
+  loadAuditConfig,
+  parseArgs,
+  renderHtml,
+  run,
+  toAuditContractReport,
+};
+
+if (require.main === module) {
+  run();
+}

package/src/cli/doctor.js

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { normalizeTokenSourceFormat } = require('../utils/token-sources');
 
 const cwd = process.cwd();
 let issues = 0;
@@ -205,6 +206,99 @@ function checkCustomSyntax(configContent) {
   }
 }
 
+function checkRhythmguardConfig() {
+  const configPath = path.join(cwd, '.rhythmguardrc.json');
+  if (!fs.existsSync(configPath)) {
+    skip('rhythmguard config check skipped (.rhythmguardrc.json not found)');
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    fail('.rhythmguardrc.json is not valid JSON', 'Fix or remove .rhythmguardrc.json');
+    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;
+  }
+
+  pass('.rhythmguardrc.json audit config valid');
+  checkRhythmguardTokenSources(audit, path.dirname(configPath));
+  checkRhythmguardMotionConfig(audit);
+  checkRhythmguardBaseline(audit);
+}
+
+function checkRhythmguardTokenSources(audit, baseDir) {
+  if (audit.tokenSources === undefined) {
+    skip('token source config check skipped (not configured)');
+    return;
+  }
+
+  if (!Array.isArray(audit.tokenSources)) {
+    fail('audit.tokenSources must be an array', 'Use strings or { "path": "...", "format": "..." } entries');
+    return;
+  }
+
+  for (const source of audit.tokenSources) {
+    const sourcePath = typeof source === 'string' ? source : source && source.path;
+    const format = typeof source === 'string' ? 'auto' : source && source.format;
+
+    if (typeof sourcePath !== 'string' || sourcePath.trim().length === 0) {
+      fail('token source entry missing path', 'Use strings or objects with a non-empty path');
+      continue;
+    }
+
+    try {
+      normalizeTokenSourceFormat(format || 'auto');
+    } catch {
+      fail(`token source format invalid for ${sourcePath}`, 'Use auto, css, flat-json, style-dictionary, or dtcg');
+    }
+
+    if (fs.existsSync(path.resolve(baseDir, sourcePath))) {
+      pass(`token source found (${sourcePath})`);
+    } else {
+      fail(`token source not found (${sourcePath})`, 'Update audit.tokenSources or create the token file');
+    }
+  }
+}
+
+function checkRhythmguardMotionConfig(audit) {
+  if (audit.includeMotion === undefined) {
+    skip('motion audit check skipped (not configured)');
+    return;
+  }
+
+  if (typeof audit.includeMotion === 'boolean') {
+    pass(`motion audit config valid (${audit.includeMotion})`);
+  } else {
+    fail('audit.includeMotion must be a boolean', 'Use true or false');
+  }
+}
+
+function checkRhythmguardBaseline(audit) {
+  const baselinePath = path.resolve(cwd, audit.baseline || '.rhythmguard-baseline.json');
+  if (!fs.existsSync(baselinePath)) {
+    skip('baseline freshness check skipped (baseline not found)');
+    return;
+  }
+
+  try {
+    const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    if (!Array.isArray(baseline.findings)) {
+      fail('baseline file does not include findings array', 'Regenerate it with rhythmguard audit --write-baseline');
+      return;
+    }
+    pass(`baseline file readable (${path.relative(cwd, baselinePath)})`);
+  } catch {
+    fail('baseline file is not valid JSON', 'Regenerate it with rhythmguard audit --write-baseline');
+  }
+}
+
 function run() {
   process.stdout.write('\nRhythmguard Doctor\n\n');
 
@@ -214,6 +308,7 @@ function run() {
   checkTokenPattern(configContent);
   checkTailwindConfig(configContent);
   checkCustomSyntax(configContent);
+  checkRhythmguardConfig();
 
   process.stdout.write('\n');
 

package/src/cli/index.js

@@ -27,7 +27,7 @@ if (!command || command === '--help' || command === '-h') {
 }
 
 if (command === 'audit') {
-  require('./audit');
+  require('./audit').run();
 } else if (command === 'init') {
   require('./init');
 } else if (command === 'doctor') {

package/src/index.js

@@ -25,3 +25,4 @@ module.exports.configs = {
 };
 module.exports.eslint = require('./eslint');
 module.exports.presets = require('./presets');
+module.exports.audit = require('./audit');

package/src/index.mjs

@@ -8,3 +8,4 @@ export const rules = plugin.rules;
 export const configs = plugin.configs;
 export const presets = plugin.presets;
 export const eslint = plugin.eslint;
+export const audit = plugin.audit;