stylelint-plugin-rhythmguard 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -6,6 +6,48 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-09-05
+
+### Added
+
+- Added `scale: "auto"` to `rhythmguard/use-scale`, `rhythmguard/no-offscale-transform` and `rhythmguard/prefer-token`. The scale is inferred from spacing tokens: `scaleSources` files, then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom properties, then `tailwindConfigPath`, with a `rhythmic-4` fallback that is announced in the first report of the file. First matching source wins.
+- Added the `scaleSources` rule option and made `tailwindConfigPath` available to every scale rule.
+- Added `rhythmguard audit --scale auto`, which infers one project-level scale from token sources, then spacing custom properties across the scanned CSS, then the default. The JSON contract now carries `contracts.scale.values`, `source` and `files`; text and Markdown output print the scale and its source.
+- Added the quiet benchmark (`npm run bench:quiet`): audits public design systems with `--scale auto`, classifies findings as drift, noise or allowance, and writes `docs/QUIET_BENCHMARK.md` with a per-repo false-positive rate. Manifest and classification rules live in `benchmarks/quiet/`.
+- Scale inference now reads token values written as `calc(<length> * var(--factor))` (Radix Themes), expands a bare Tailwind v4 `--spacing` base into the default multiplier scale, and matches prefixed spacing tokens such as `--lb-spacing-md` while excluding `letter-spacing` and `word-spacing`.
+
+- Added `docs/FOR_AGENTS.md` with a paste-ready `AGENTS.md` block and the commands a coding agent should run, and a "what it is not" paragraph at the top of the README (no color checking, class strings need the ESLint companion, no SCSS in the audit).
+- The quiet benchmark now pins each repository to a recorded commit and keeps snapshots of its findings under `benchmarks/quiet/snapshots/`. `npm run bench:quiet -- --check` fails when the finding set or the inferred scale changes, `--update-snapshots` accepts a reviewed change, `--latest` audits upstream heads. A farm workflow runs the check on every change and the upstream run weekly.
+- `npx rhythmguard` with no command now runs a zero-config quickstart: detects Tailwind (and its major version), Next.js, an existing Stylelint config and token files; infers the spacing scale from the project's own tokens; audits the current directory; and prints the exact `.stylelintrc.json` (plus an ESLint snippet for Tailwind) to paste. `--help` is unchanged; `rhythmguard quickstart` is an explicit alias.
+- Added `stylelint-plugin-rhythmguard/configs/embed`: `use-scale` at warning level with `scale: "auto"`, no `extends`, shape frozen for 2.x. The entry point for shared-config authors who want to enable spacing governance for their consumers without knowing each consumer's scale. Guide in `docs/FOR_CONFIG_AUTHORS.md`.
+- Added `allowHairlines` (default `true`) to `use-scale`, `no-offscale-transform` and `prefer-token`. Non-zero lengths that resolve to one CSS pixel or less (`1px`, `-1px`, `0.5px`, `0.0625rem`) are exempt: they compensate for borders and rendering, not spacing. The quiet benchmark showed them to be the only systematic false positive left across Radix Themes, Mantine, Primer React and Liveblocks. Set `allowHairlines: false` to restore the previous reports.
+
+### Fixed
+
+- `rhythmguard/prefer-token` no longer reports percentages such as `translate(-50%, -50%)` or `inset: 100%` as raw scale values. Percentages are never token candidates. This was the largest noise source in the quiet benchmark.
+- `rhythmguard/use-scale` with `allowPercentages: false` now reports percentage lengths instead of silently skipping them.
+
+## [2.1.0] - 2026-09-05
+
+### Added
+
+- Added `rhythmguard audit --format github`, emitting GitHub Actions workflow-command annotations (one `::warning` per finding, a `::notice` summary) for inline PR feedback without a formatter dependency.
+- Added per-rule documentation pages under `docs/rules/` for every Stylelint and ESLint rule. Rule `meta.url` and ESLint `meta.docs.url` now point at them, and a test enforces the link.
+- Added `npm run typecheck`: compiles the published TypeScript declarations, a consumer check file, and the packaged examples.
+- Added Stylelint 17 to the CI and release matrices (Node 20 and 22; Node 18 is excluded for Stylelint 17).
+- Added a bug-report issue template.
+
+### Changed
+
+- README cut from 833 lines to a quick start. Config details, scale presets, the audit reference and the full custom setup moved to `docs/CONFIGS.md`, `docs/SCALE_PRESETS.md` and `docs/AUDIT.md`; development and release notes moved to `CONTRIBUTING.md`.
+- Split the audit CLI into focused modules under `src/audit/`; `src/cli/audit.js` is now a thin command shell. No behaviour change.
+- Release, post-publish smoke and community-scale workflows now run on the self-hosted runners like CI.
+
+### Fixed
+
+- `plugin.configs` and the ESM entry now expose `react-tailwind`, matching the `./configs/react-tailwind` package export. A test asserts parity between package exports and the programmatic configs object.
+- `AuditOptions` declaration: `config` and `output` were never read by the audit API and are replaced by the real keys `configPath` and `outputPath`; `noConfig` and `tokenSourceFormat` added.
+
 ## [2.0.1] - 2026-06-17
 
 ### Added

package/CONTRIBUTING.md

@@ -37,6 +37,21 @@ npm run scales:validate
 
 Scale files must pass schema and collision checks. See [`docs/COMMUNITY_SCALES.md`](./docs/COMMUNITY_SCALES.md) for the full spec and policy.
 
+## Compatibility Targets
+
+- Stylelint `^16.0.0 || ^17.0.0`. Stylelint `16.0.0` has known autofix and API differences; CI runs the floor-compat suite against it and the full suite non-blocking.
+- Node `>=18.18.0` for Stylelint 16, `>=20.19.0` for Stylelint 17. The CI matrix excludes Node 18 with Stylelint 17.
+- Dual CommonJS and ESM entry points; every export has a declaration under `types/`. `npm run typecheck` compiles the declarations, a consumer check file, and the examples.
+
+## Performance Benchmarking
+
+```bash
+npm run bench:perf
+npm run bench:perf:fix
+```
+
+Compares runtime against `stylelint-scales` on a deterministic corpus. Method and arguments: [`docs/BENCHMARKING.md`](./docs/BENCHMARKING.md).
+
 ## Semver Rules
 
 - Patch (`x.y.Z`): bug fixes, docs updates, non-breaking internal changes.
@@ -55,11 +70,15 @@ When changing rule logic:
 
 1. add/adjust tests for the behavior
 2. validate deterministic fix behavior
-3. update README option or behavior docs if needed
+3. update the rule's page in `docs/rules/` if options or behavior changed
 4. update CHANGELOG
+5. run the quiet benchmark: `npm run bench:quiet -- --check`. It audits real public design systems at pinned commits and fails when the finding set or the inferred scale changes. If the change is intended, review the printed diff, run `npm run bench:quiet -- --update-snapshots`, and commit `benchmarks/quiet/snapshots/` with a sentence in the PR on why the new findings are right. CI runs the same check.
+
+## Release Workflow
 
-## Release Notes
+1. Run the local gate: `npm run lint && npm run typecheck && npm test && npm run test:pack-smoke`.
+2. Update `CHANGELOG.md` and bump `package.json`.
+3. Create a GitHub release. `release.yml` runs the Node and Stylelint matrix on the self-hosted runners, then publishes to npm with provenance when `NPM_TOKEN` is configured, or skips publish with a notice when it is not.
+4. `post-publish-smoke.yml` installs the published version in a clean project.
 
-- Keep `stylelint-plugin-rhythmguard/configs/recommended` and `stylelint-plugin-rhythmguard/configs/strict` stable.
-- Verify CI matrix is green before publishing.
-- Publish with provenance through the release workflow.
+Keep `configs/recommended` and `configs/strict` stable across minors. Rule docs live in `docs/rules/`; a test checks that every rule's `meta.url` points at its page.