stylelint-plugin-rhythmguard 1.9.0 → 2.0.1

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-06-17
+
+### Added
+
+- Added TypeScript declaration files for the public plugin, config, rule, preset, ESLint companion, and Audit 2.0 API exports.
+- Added dependency-free Audit 2.0 dashboard and Figma-friendly export examples under `examples/`.
+- Added CI adoption and motion-default evidence docs for safer baseline-based rollout.
+
+### Fixed
+
+- Fixed `rhythmguard init` scripted input handling so multiple prompts work reliably in piped/CI contexts.
+
+## [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
@@ -251,6 +291,8 @@ Framework-specific setup for Vue, Lit, Astro, and SvelteKit: [`docs/FRAMEWORKS.m
 
 - Side-by-side tool fit guide with migration snippets: [`docs/COMPARISON.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/COMPARISON.md)
 - Audit 2.0 validation and roadmap: [`docs/AUDIT_2_VALIDATION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/AUDIT_2_VALIDATION.md)
+- CI baseline rollout recipe: [`docs/CI_ADOPTION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/CI_ADOPTION.md)
+- Programmatic dashboard and Figma-friendly export examples: [`docs/AUDIT_API_EXAMPLES.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/AUDIT_API_EXAMPLES.md)
 - Real-world before/after excerpts from public repos: [`docs/ADOPTION_DIFFS.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/ADOPTION_DIFFS.md)
 - Distribution submissions to Stylelint discovery surfaces: [`docs/DISTRIBUTION.md`](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/blob/main/docs/DISTRIBUTION.md)
 

package/examples/audit-dashboard.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createAuditReport, toAuditContractReport } from 'stylelint-plugin-rhythmguard/audit';
+
+function readOption(argv, name, fallback) {
+  const index = argv.indexOf(name);
+  if (index === -1 || !argv[index + 1] || argv[index + 1].startsWith('--')) {
+    return fallback;
+  }
+
+  return argv[index + 1];
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function collectFindings(findings) {
+  return [
+    ...(findings.css || []),
+    ...(findings.tailwind || []),
+    ...(findings.motion || []),
+  ];
+}
+
+function renderMetric(label, value) {
+  return `<article class="metric"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></article>`;
+}
+
+function renderDashboard(contract) {
+  const findings = collectFindings(contract.findings);
+  const topFindings = findings.slice(0, 12);
+  const cleanliness = contract.contracts.scale.cleanliness;
+  const score = typeof cleanliness === 'number' ? cleanliness : contract.summary.cleanliness;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Rhythmguard Audit Dashboard</title>
+<style>
+body{font-family:Inter,ui-sans-serif,system-ui,sans-serif;margin:0;background:#f7f8fa;color:#111827;}
+main{max-width:1120px;margin:0 auto;padding:32px 20px;}
+h1{font-size:28px;margin:0 0 8px;}
+p{color:#4b5563;margin:0 0 24px;}
+.metrics{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:12px;margin:24px 0;}
+.metric{border:1px solid #d8dde5;background:#fff;border-radius:8px;padding:16px;}
+.metric span{display:block;color:#6b7280;font-size:12px;text-transform:uppercase;}
+.metric strong{display:block;font-size:28px;margin-top:8px;}
+table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #d8dde5;border-radius:8px;overflow:hidden;}
+th,td{text-align:left;border-bottom:1px solid #e5e7eb;padding:10px 12px;font-size:14px;}
+th{background:#f1f5f9;color:#374151;font-size:12px;text-transform:uppercase;}
+tr:last-child td{border-bottom:0;}
+code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px;}
+</style>
+</head>
+<body>
+<main>
+<h1>Rhythmguard Audit Dashboard</h1>
+<p>${escapeHtml(contract.command.directory)} · ${escapeHtml(contract.command.scanScope)} · schema ${escapeHtml(contract.schemaVersion)}</p>
+<section class="metrics">
+${renderMetric('Scale cleanliness', `${score ?? 100}%`)}
+${renderMetric('CSS files', contract.scanned.cssFiles)}
+${renderMetric('Template files', contract.scanned.templateFiles)}
+${renderMetric('Findings', findings.length)}
+</section>
+<table>
+<thead><tr><th>Type</th><th>File</th><th>Value</th><th>Message</th></tr></thead>
+<tbody>
+${topFindings.map((finding) => `<tr><td>${escapeHtml(finding.type)}</td><td><code>${escapeHtml(finding.file)}</code></td><td><code>${escapeHtml(finding.value || finding.rawValue || '')}</code></td><td>${escapeHtml(finding.message || '')}</td></tr>`).join('\n')}
+</tbody>
+</table>
+</main>
+</body>
+</html>`;
+}
+
+const argv = process.argv.slice(2);
+const dir = readOption(argv, '--dir', argv.find((arg) => !arg.startsWith('--')) || 'src');
+const output = readOption(argv, '--output', 'rhythmguard-dashboard.html');
+const includeMotion = argv.includes('--include-motion');
+
+const report = await createAuditReport({ dir, includeMotion });
+const contract = toAuditContractReport(report);
+const outputPath = path.resolve(process.cwd(), output);
+
+fs.writeFileSync(outputPath, renderDashboard(contract));
+process.stdout.write(`Wrote ${outputPath}\n`);

package/examples/audit-figma-export.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createAuditReport, toAuditContractReport } from 'stylelint-plugin-rhythmguard/audit';
+
+function readOption(argv, name, fallback) {
+  const index = argv.indexOf(name);
+  if (index === -1 || !argv[index + 1] || argv[index + 1].startsWith('--')) {
+    return fallback;
+  }
+
+  return argv[index + 1];
+}
+
+function collectFindings(findings) {
+  return [
+    ...(findings.css || []),
+    ...(findings.tailwind || []),
+    ...(findings.motion || []),
+  ];
+}
+
+function countBy(items, getKey) {
+  const counts = new Map();
+  for (const item of items) {
+    const key = getKey(item) || 'unknown';
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([label, value]) => ({ label, value }));
+}
+
+function buildFigmaPayload(contract) {
+  const findings = collectFindings(contract.findings);
+  const cleanliness = contract.contracts.scale.cleanliness;
+
+  return {
+    schema: 'rhythmguard.figma-export.v1',
+    generatedAt: new Date().toISOString(),
+    source: {
+      directory: contract.command.directory,
+      scanScope: contract.command.scanScope,
+      schemaVersion: contract.schemaVersion,
+    },
+    summaryCards: [
+      {
+        label: 'Scale cleanliness',
+        value: `${typeof cleanliness === 'number' ? cleanliness : contract.summary.cleanliness ?? 100}%`,
+      },
+      { label: 'CSS files', value: contract.scanned.cssFiles },
+      { label: 'Template files', value: contract.scanned.templateFiles },
+      { label: 'Findings', value: findings.length },
+    ],
+    charts: {
+      findingsByType: countBy(findings, (finding) => finding.type),
+      findingsByFile: countBy(findings, (finding) => finding.file).slice(0, 10),
+    },
+    findings: findings.slice(0, 25).map((finding) => ({
+      file: finding.file,
+      line: finding.line || null,
+      message: finding.message || '',
+      type: finding.type,
+      value: finding.value || finding.rawValue || null,
+    })),
+  };
+}
+
+const argv = process.argv.slice(2);
+const dir = readOption(argv, '--dir', argv.find((arg) => !arg.startsWith('--')) || 'src');
+const output = readOption(argv, '--output', 'rhythmguard-figma-export.json');
+const includeMotion = argv.includes('--include-motion');
+
+const report = await createAuditReport({ dir, includeMotion });
+const contract = toAuditContractReport(report);
+const outputPath = path.resolve(process.cwd(), output);
+
+fs.writeFileSync(outputPath, `${JSON.stringify(buildFigmaPayload(contract), null, 2)}\n`);
+process.stdout.write(`Wrote ${outputPath}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "1.9.0",
+  "version": "2.0.1",
   "description": "Token governance for CSS and Tailwind — enforce spacing scales, require design tokens, catch arbitrary values",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -20,72 +20,95 @@
   ],
   "type": "commonjs",
   "main": "src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "require": "./src/index.js",
       "import": "./src/index.mjs"
     },
     "./configs/recommended": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/recommended.js",
       "import": "./src/configs/recommended.mjs"
     },
     "./configs/strict": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/strict.js",
       "import": "./src/configs/strict.mjs"
     },
     "./configs/tailwind": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/tailwind.js",
       "import": "./src/configs/tailwind.mjs"
     },
     "./configs/expanded": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/expanded.js",
       "import": "./src/configs/expanded.mjs"
     },
     "./configs/logical": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/logical.js",
       "import": "./src/configs/logical.mjs"
     },
     "./configs/migration": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/migration.js",
       "import": "./src/configs/migration.mjs"
     },
     "./configs/motion": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/motion.js",
       "import": "./src/configs/motion.mjs"
     },
     "./configs/react-tailwind": {
+      "types": "./types/config.d.ts",
       "require": "./src/configs/react-tailwind.js",
       "import": "./src/configs/react-tailwind.mjs"
     },
     "./presets": {
+      "types": "./types/presets.d.ts",
       "require": "./src/presets/index.js",
       "import": "./src/presets/index.mjs"
     },
+    "./audit": {
+      "types": "./types/audit.d.ts",
+      "require": "./src/audit/index.js",
+      "import": "./src/audit/index.mjs"
+    },
     "./rules/use-scale": {
+      "types": "./types/rule.d.ts",
       "require": "./src/rules/use-scale/index.js",
       "import": "./src/rules/use-scale/index.mjs"
     },
     "./rules/prefer-token": {
+      "types": "./types/rule.d.ts",
       "require": "./src/rules/prefer-token/index.js",
       "import": "./src/rules/prefer-token/index.mjs"
     },
     "./rules/no-offscale-transform": {
+      "types": "./types/rule.d.ts",
       "require": "./src/rules/no-offscale-transform/index.js",
       "import": "./src/rules/no-offscale-transform/index.mjs"
     },
     "./rules/use-motion-scale": {
+      "types": "./types/rule.d.ts",
       "require": "./src/rules/use-motion-scale/index.js",
       "import": "./src/rules/use-motion-scale/index.mjs"
     },
     "./eslint": {
+      "types": "./types/eslint.d.ts",
       "require": "./src/eslint/index.js",
       "import": "./src/eslint/index.mjs"
     }
   },
   "files": [
+    "examples",
     "scales",
     "schemas",
     "src",
+    "types",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",

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;