stylelint-plugin-rhythmguard 1.8.0 → 2.0.0

package/src/cli/audit.js

@@ -6,6 +6,8 @@ const path = require('node:path');
 
 const { formatLength } = require('../utils/length');
 const { createTailwindClassAnalyzer } = require('../utils/tailwind-class-analysis');
+const { createTailwindMotionAnalyzer } = require('../utils/tailwind-motion-analysis');
+const { formatTime } = require('../utils/time');
 const {
   addDefinition,
   createTokenKindMatcher,
@@ -23,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',
@@ -54,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)
@@ -69,39 +74,17 @@ Options:
   --min-cleanliness <percent>    Exit 1 when scale cleanliness is lower than this percent
   --since <git-ref>              Scan only changed files since a git ref
   --staged                       Scan only staged files
+  --include-motion               Include opt-in motion duration/easing drift
   --token-source <file>          External token source (repeatable, comma-separated)
   --token-source-format <format> Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)
-  --token-kind <kind>            Token kind: spacing, radius, typography, size, all (default: spacing)
+  --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
   --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
   --scale <values>               Comma-separated scale values (default: 0,4,8,12,16,24,32)
   --base-font-size <number>      px base for rem/em conversion (default: 16)
 `;
 
 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: [],
-    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];
@@ -111,6 +94,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--schema') {
+      parsed.schema = true;
+      parsed.format = 'json';
+      continue;
+    }
+
     if (arg === '--json') {
       parsed.format = 'json';
       continue;
@@ -121,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');
@@ -261,6 +262,12 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--include-motion') {
+      parsed.includeMotion = true;
+      parsed.cliOptions.add('includeMotion');
+      continue;
+    }
+
     if (arg === '--token-source') {
       parsed.tokenSources.push(...parseTokenSourcePaths(argv[++index]));
       parsed.cliOptions.add('tokenSources');
@@ -355,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) {
@@ -369,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}.`);
@@ -476,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;
   }
@@ -572,6 +611,7 @@ function applyAuditConfig(parsed, configResult) {
   applyConfigScalar(next, audit, cliOptions, 'tokenCandidateMinCount', 'tokenCandidateMinCount', parsePositiveInteger);
   applyConfigScalar(next, audit, cliOptions, 'tokenKind', 'tokenKind', normalizeTokenKind);
   applyConfigScalar(next, audit, cliOptions, 'baseFontSize', 'baseFontSize', parseBaseFontSize);
+  applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
   applyConfigScalar(next, audit, cliOptions, 'scale', 'scale', (value) => {
     if (Array.isArray(value)) {
       return value;
@@ -591,6 +631,14 @@ function applyConfigScalar(target, audit, cliOptions, targetKey, configKey, pars
   target[targetKey] = parser(audit[configKey], configKey);
 }
 
+function parseBooleanOption(value, optionName) {
+  if (typeof value !== 'boolean') {
+    throw new Error(`${optionName} must be a boolean.`);
+  }
+
+  return value;
+}
+
 function normalizeCliTokenSources(sources, format) {
   return sources.map((sourcePath) => ({
     baseDir: process.cwd(),
@@ -866,31 +914,41 @@ async function runStylelintAudit(cssFiles, options) {
   }
 
   const { default: stylelint } = await import('stylelint');
+  const rules = {
+    'rhythmguard/use-scale': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+      },
+    ],
+    'rhythmguard/prefer-token': [
+      true,
+      {
+        baseFontSize: options.baseFontSize,
+        scale: options.scale,
+        severity: 'warning',
+        tokenMapFromCssCustomProperties: true,
+        tokenPattern: DEFAULT_AUDIT_TOKEN_PATTERN,
+      },
+    ],
+  };
+
+  if (options.includeMotion) {
+    rules['rhythmguard/use-motion-scale'] = [
+      true,
+      {
+        severity: 'warning',
+      },
+    ];
+  }
 
   const result = await stylelint.lint({
     files: cssFiles,
     config: {
       plugins: [pluginPath],
-      rules: {
-        'rhythmguard/use-scale': [
-          true,
-          {
-            baseFontSize: options.baseFontSize,
-            scale: options.scale,
-            severity: 'warning',
-          },
-        ],
-        'rhythmguard/prefer-token': [
-          true,
-          {
-            baseFontSize: options.baseFontSize,
-            scale: options.scale,
-            severity: 'warning',
-            tokenMapFromCssCustomProperties: true,
-            tokenPattern: '^--spac(e|ing)-',
-          },
-        ],
-      },
+      rules,
     },
   });
 
@@ -909,6 +967,12 @@ function collectCssFindings(fileResults) {
       const tokenMatch = text.match(
         /Unexpected raw scale value "([^"]+)"/,
       );
+      const motionDurationMatch = text.match(
+        /Unexpected (?:motion duration|negative motion duration) "([^"]+)"/,
+      );
+      const motionEasingMatch = text.match(
+        /Unexpected raw motion easing "([^"]+)"/,
+      );
 
       findings.push({
         column: warning.column || 1,
@@ -916,8 +980,13 @@ function collectCssFindings(fileResults) {
         line: warning.line || 1,
         rule: warning.rule || 'rhythmguard',
         text,
-        type: tokenMatch ? 'token-opportunity' : 'off-scale',
-        value: tokenMatch ? tokenMatch[1] : offScaleMatch ? offScaleMatch[1] : null,
+        type: getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }),
+        value: getCssFindingValue({
+          motionDurationMatch,
+          motionEasingMatch,
+          offScaleMatch,
+          tokenMatch,
+        }),
       });
     }
   }
@@ -925,6 +994,47 @@ function collectCssFindings(fileResults) {
   return findings;
 }
 
+function getCssFindingValue({
+  motionDurationMatch,
+  motionEasingMatch,
+  offScaleMatch,
+  tokenMatch,
+}) {
+  if (tokenMatch) {
+    return tokenMatch[1];
+  }
+
+  if (offScaleMatch) {
+    return offScaleMatch[1];
+  }
+
+  if (motionDurationMatch) {
+    return motionDurationMatch[1];
+  }
+
+  if (motionEasingMatch) {
+    return motionEasingMatch[1];
+  }
+
+  return null;
+}
+
+function getCssFindingType({ motionDurationMatch, motionEasingMatch, tokenMatch }) {
+  if (motionDurationMatch) {
+    return 'motion-duration';
+  }
+
+  if (motionEasingMatch) {
+    return 'motion-easing';
+  }
+
+  if (tokenMatch) {
+    return 'token-opportunity';
+  }
+
+  return 'off-scale';
+}
+
 function collectTailwindFindings(templateFiles, options) {
   const analyzer = createTailwindClassAnalyzer(options);
   const findings = [];
@@ -969,6 +1079,66 @@ function collectTailwindFindings(templateFiles, options) {
   return findings;
 }
 
+function collectTailwindMotionFindings(templateFiles, options) {
+  if (!options.includeMotion) {
+    return [];
+  }
+
+  const analyzer = createTailwindMotionAnalyzer(options);
+  const findings = [];
+
+  for (const filePath of templateFiles) {
+    let source = '';
+    try {
+      source = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const lineStarts = getLineStarts(source);
+
+    for (const literal of findStringLiterals(source)) {
+      for (const { analysis, segment } of analyzer.analyzeClassString(literal.value)) {
+        const position = offsetToLineColumn(lineStarts, literal.valueStart + segment.start);
+        findings.push({
+          column: position.column,
+          file: formatPath(filePath),
+          fixedToken: analysis.fixedToken,
+          line: position.line,
+          nearest: analysis.nearest
+            ? {
+              lower: formatTime(analysis.nearest.lower, 'ms'),
+              upper: formatTime(analysis.nearest.upper, 'ms'),
+            }
+            : null,
+          rawValue: analysis.rawValue,
+          rule: 'rhythmguard-tailwind/tailwind-class-use-motion-scale',
+          text: buildTailwindMotionFindingText(segment.token, analysis),
+          token: segment.token,
+          type: analysis.reason === 'easing'
+            ? 'tailwind-motion-easing'
+            : 'tailwind-motion-duration',
+          utility: analysis.utility,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function buildTailwindMotionFindingText(token, analysis) {
+  if (analysis.reason === 'easing') {
+    return `Unexpected Tailwind arbitrary motion easing "${token}". Use motion tokens for easing decisions.`;
+  }
+
+  if (analysis.reason === 'negative') {
+    return `Unexpected Tailwind arbitrary motion duration "${token}". Use non-negative duration values.`;
+  }
+
+  return `Unexpected Tailwind arbitrary motion duration "${token}". Use duration scale values.`;
+}
+
 function findStringLiterals(source) {
   const literals = [];
   const literalPattern = /(["'`])((?:\\[\s\S]|(?!\1)[\s\S])*?)\1/g;
@@ -1250,6 +1420,8 @@ function buildReport({
   cssFindings,
   dir,
   externalTokenDefinitions,
+  includeMotion,
+  motionFindings,
   scanScope,
   templateFiles,
   tailwindFindings,
@@ -1266,17 +1438,21 @@ function buildReport({
     .map((finding) => finding.value));
   const tailwindArbitraryValues = countByValue(tailwindFindings
     .map((finding) => finding.rawValue));
+  const motionValues = countByValue(motionFindings
+    .map((finding) => finding.value || finding.rawValue));
   const issueFiles = new Set([
     ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
     ...tailwindFindings.map((finding) => finding.file),
   ]);
   const topAffectedFiles = sortCountMap(countByValue([
     ...cssFindings.map((finding) => finding.file),
+    ...motionFindings.map((finding) => finding.file),
     ...tailwindFindings.map((finding) => finding.file),
   ])).slice(0, 10);
 
   const totalFiles = cssFiles.length + templateFiles.length;
-  const totalWarnings = cssFindings.length + tailwindFindings.length;
+  const totalWarnings = cssFindings.length + motionFindings.length + tailwindFindings.length;
   const filesWithIssues = issueFiles.size;
   const scaleCleanliness = totalFiles > 0
     ? Math.max(0, Math.round(((totalFiles - filesWithIssues) / totalFiles) * 100))
@@ -1299,9 +1475,15 @@ function buildReport({
     filesWithIssues,
     findings: {
       css: cssFindings,
+      motion: motionFindings,
       tailwind: tailwindFindings,
     },
-    formatVersion: 4,
+    formatVersion: 5,
+    motion: {
+      enabled: includeMotion,
+      findings: motionFindings.length,
+      values: Object.fromEntries(sortCountMap(motionValues).slice(0, 10)),
+    },
     offScaleValues: Object.fromEntries(sortCountMap(offScaleValues).slice(0, 10)),
     scaleCleanliness,
     scanScope,
@@ -1313,6 +1495,7 @@ function buildReport({
     summary: {
       cssWarnings: cssFindings.length,
       filesWithIssues,
+      motionFindings: motionFindings.length,
       rawValueMatches: tokenContract.summary.rawValueMatches,
       missingTokens: tokenContract.summary.missingTokens,
       rawValueCandidates: tokenContract.summary.rawValueCandidates,
@@ -1405,6 +1588,7 @@ function writeBaseline(report, baselinePath) {
 function getAllFindings(report) {
   return [
     ...report.findings.css,
+    ...report.findings.motion,
     ...report.findings.tailwind,
   ];
 }
@@ -1470,6 +1654,7 @@ function renderText(report) {
   appendHistogram(lines, 'CSS OFF-SCALE VALUES', report.offScaleValues);
   appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
   appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
+  appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
   appendTokenContractText(lines, report.tokenContract);
   appendBaselineText(lines, report);
 
@@ -1622,6 +1807,7 @@ function renderMarkdown(report) {
   appendMarkdownCounts(lines, 'CSS Off-Scale Values', report.offScaleValues);
   appendMarkdownCounts(lines, 'CSS Token Opportunities', report.tokenOpportunities);
   appendMarkdownCounts(lines, 'Tailwind Class-String Drift', report.tailwindArbitraryValues);
+  appendMarkdownCounts(lines, 'Motion Rhythm Drift', report.motion.values);
   appendTokenContractMarkdown(lines, report.tokenContract);
   appendBaselineMarkdown(lines, report);
 
@@ -1828,76 +2014,49 @@ 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,
     sources: parsed.tokenSources,
     tokenKind: parsed.tokenKind,
   });
+  const stylelintFindings = collectCssFindings(cssResults);
+  const cssFindings = stylelintFindings.filter((finding) => !finding.type.startsWith('motion-'));
+  const motionFindings = [
+    ...stylelintFindings.filter((finding) => finding.type.startsWith('motion-')),
+    ...collectTailwindMotionFindings(templateFiles, lintOptions),
+  ];
 
   const report = buildReport({
     baseFontSize: parsed.baseFontSize,
     config: parsed.config,
     cssFiles,
-    cssFindings: collectCssFindings(cssResults),
+    cssFindings,
     dir: parsed.dir,
     externalTokenDefinitions: tokenSourceResult.definitions,
+    includeMotion: parsed.includeMotion,
+    motionFindings,
     scanScope,
-    tailwindFindings: collectTailwindFindings(templateFiles, options),
+    tailwindFindings: collectTailwindFindings(templateFiles, lintOptions),
     templateFiles,
     tokenCandidateMinCount: parsed.tokenCandidateMinCount,
     tokenKind: parsed.tokenKind,
@@ -1905,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);
@@ -1921,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;
@@ -1945,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();
+}