stylelint-plugin-rhythmguard 3.18.0 → 3.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.md +4 -4
  4. package/SECURITY.md +14 -0
  5. package/agents/claude-code/SKILL.md +14 -1
  6. package/agents/copilot/{copilot-instructions.md → rhythmguard.instructions.md} +7 -1
  7. package/agents/cursor/rhythmguard.mdc +5 -3
  8. package/package.json +2 -2
  9. package/src/audit/args.js +30 -8
  10. package/src/audit/baseline.js +44 -2
  11. package/src/audit/codemod.js +2 -0
  12. package/src/audit/config.js +7 -0
  13. package/src/audit/contract.js +131 -17
  14. package/src/audit/next-steps.js +86 -0
  15. package/src/audit/non-authored.js +1 -0
  16. package/src/audit/render-github.js +52 -15
  17. package/src/audit/render-markdown.js +58 -17
  18. package/src/audit/render-text.js +76 -6
  19. package/src/audit/render-utils.js +14 -0
  20. package/src/audit/report.js +235 -10
  21. package/src/audit/scan/files.js +5 -0
  22. package/src/audit/scan/stylesheets.js +63 -59
  23. package/src/audit/scan/templates.js +2 -0
  24. package/src/audit/shared.js +7 -1
  25. package/src/audit/token-chains.js +1 -0
  26. package/src/cli/audit.js +20 -11
  27. package/src/cli/doctor.js +853 -237
  28. package/src/cli/first-run.js +210 -0
  29. package/src/cli/index.js +25 -1
  30. package/src/cli/index.mjs +3 -0
  31. package/src/cli/init.js +75 -26
  32. package/src/cli/quickstart.js +109 -118
  33. package/src/cli/scale.js +223 -0
  34. package/src/configs/recommended.js +3 -1
  35. package/src/configs/strict.js +3 -1
  36. package/src/configs/tailwind.js +15 -0
  37. package/src/core/decisions.js +18 -5
  38. package/src/core/fs-cache.js +1 -0
  39. package/src/core/options.js +2 -1
  40. package/src/core/scale-inference.js +72 -52
  41. package/src/core/tailwind-class-analysis.js +56 -13
  42. package/src/core/token-index.js +55 -14
  43. package/src/core/token-map.js +140 -88
  44. package/src/core/token-sources.js +461 -40
  45. package/src/core/value-nodes.js +4 -2
  46. package/src/eslint/class-context.js +330 -0
  47. package/src/eslint/literal-spans.js +5 -4
  48. package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
  49. package/src/presets/default-scale.js +42 -0
  50. package/src/presets/scales.js +6 -1
  51. package/src/rules/no-offscale-transform/index.js +17 -5
  52. package/src/rules/prefer-token/index.js +51 -15
  53. package/src/rules/use-scale/index.js +7 -4
  54. package/types/__checks__/consumer.ts +17 -0
  55. package/types/__checks__/eslint-config.ts +5 -0
  56. package/types/audit.d.ts +42 -3
  57. package/types/cli.d.ts +77 -1
  58. package/types/shared.d.ts +10 -0
package/CHANGELOG.md CHANGED
@@ -6,6 +6,74 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.20.0] - 2026-11-11
10
+
11
+ ### Changed
12
+
13
+ - The quickstart's pasted config reproduces its report. When the audit took the scale from tokens in a stylesheet, the config points `scaleSources` at that stylesheet; before, `scale: "auto"` read only the file being linted, so every other file fell back and 40px passed in the editor and failed in the audit. On a Tailwind v3 project with a config file the paste sets `tailwindConfigPath` and the next commands pass `--tailwind-config` (the quickstart itself does not load the config). It also prints the `.rhythmguardrc.json` that makes a bare `npx rhythmguard audit .` use the same scale. A contract test lints five first-run stacks with the pasted config and checks the problem count equals the audit's (dx-02, ai-01, tf-06).
14
+ - `init` writes exactly the config the quickstart pastes, from the same inference, shows a line diff of what it replaces before asking to overwrite, and offers to write the `.rhythmguardrc.json`. Before, it wrote `extends` alone, so `init`, the quickstart and the audit judged one project by three scales, and overwriting a quickstart config lost its `scaleSources` without showing it (dx-06).
15
+ - `--scale auto` in a Tailwind project with no tokens falls back to Tailwind's default ladder, the fallback `configs/tailwind` uses, instead of the default scale; `contracts.scale.preset` names the fallback. Findings only go away (css-01).
16
+ - One default scale. The audit without `--scale`, the audit's `--scale auto` fallback, `use-scale` with no `scale`, `configs/recommended`, `configs/strict` and the `rhythmic-4` preset now read one list, `0, 4, 8, 12, 16, 24, 32, 40, 48, 64`, exported once. Before, the audit stopped at 32, so 40, 48 and 64px were findings in the audit and not in Stylelint, and `init`, the quickstart and the audit judged one project by three scales. Audit findings only go away: on the quiet benchmark, 31 rows that fall back to the default lose 40, 48 and 64px findings and none gains one (dx-06, ai-01).
17
+ - `tailwind-class-use-scale` with no `scale` checks Tailwind's default spacing ladder on `spacingUnit` (`0, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, ... 384` on a 16px root) instead of `[0, 4, 8, 12, 16, 24, 32]`, and its messages end with `Scale: Tailwind default spacing.` `p-[20px]`, `p-[40px]` and `p-[2px]` are standard `p-5`, `p-10` and `p-0.5`, not findings. A value past the top step is still reported but no longer fixed: `p-[64px]` on a scale that ends at 32 was rewritten to `p-8`, halving the padding. With `scale` set, messages are unchanged (cs-01).
18
+ - The audit checks class strings against the same Tailwind ladder when the stylesheet scale is the default or the fallback, so it agrees with the ESLint rule; `contracts.scale.classStrings` and a "Class-string scale" line say so (cs-05).
19
+ - `configs/tailwind` sets `scale: "auto"` on `use-scale` and `no-offscale-transform`, falling back to Tailwind's default ladder instead of `rhythmic-4`. `padding: 20px`, `margin: 28px` and `inset: 44px` are Tailwind steps and no longer reported or rewritten to 16, 24 and 40px (css-01).
20
+ - The ESLint rule `tailwind-class-use-scale` checks class strings, not every string in a JS or TS file. Class contexts are always checked: the `className`, `class` and `*ClassName` JSX attributes and object properties; the arguments of `cn`, `clsx`, `classnames`, `cx`, `cva`, `tv`, `twMerge` and `twJoin`, with nested arrays, object keys, conditionals and `cva`/`tv` config objects; `tw` tagged templates. Any other string is checked only when it holds two or more utility-shaped tokens. Type positions (literal types, template literal types, enum members, interface and type alias members) and every other JSX, Vue or Svelte attribute (`aria-*`, `title`, `id`, `data-*`, `alt`, `placeholder`, component props) are never checked. Before, `eslint --fix` rewrote `type Size = 'p-[13px]'`, enum members, `aria-label` and `title` values, `Object.freeze({ Tight: 'p-[13px]' })` and prose. Findings outside class contexts go away, which is the intended decrease; a lone class in a plain variable (`const pad = 'p-[13px]'`) is one of them. New options `classFunctions` and `classContexts` add helper names and attribute names to the built-in lists. Vue and Svelte templates keep their `class` gate. `rhythmguard audit` still reads every string literal in a template file: its scan has no parser, and giving it one per template language is a larger change. (cs-04, fix-09, cs-08)
21
+ - Tailwind has no negative padding, scroll padding or gap, so the ESLint rule and the audit no longer suggest or write `-p-3` or `-gap-3`. An off-scale `-p-[13px]`, `p-[-13px]`, `-gap-[13px]` or `gap-[-13px]` is still reported, with no fix and the message `Unexpected Tailwind arbitrary spacing value "-p-[13px]". Padding and gap cannot be negative, so this class has no effect.` The first sentence is unchanged; the advice after it named a class that does not exist. Margin, inset, `top`/`right`/`bottom`/`left`, translate, `scroll-m*` and `space-*` keep their negative forms. (cs-04, fix-09, cs-08)
22
+ - Token sources whose names give no spacing length are read again instead of falling back. Names count in any case and with a camelCase or digit boundary (`--spacingXs` from `@tokens-studio/sd-transforms`, `--Space-1`, Style Dictionary's `Space1`), and in JSON a token typed as a dimension counts whatever its name (DTCG `$type: "dimension"`, or a `type` of `spacing`, `sizing` or `dimension`), unless its name says radius, font, border or another kind. A file whose names already gave a scale keeps exactly that scale. Tokens Studio exports are detected (`format: "tokens-studio"`) and read set by set in `tokenSetOrder` without the set name, with unitless spacing values as px and `+ - * /` over references evaluated. A DTCG 2025.10 `$root` token is read as its group's token (`space.$root` is `--space`), and a `$deprecated` token is listed as deprecated and never written by a fix or offered in a message; in 3.x its value stays on the scale, so no finding is added, and it leaves the scale in 4.0. Each entry in `contracts.tokens.sources` gains `selectedBy` (`name`, `type` or `tokenPattern`) and, when any, `deprecated`. Role-named DTCG, camelCase and Tokens Studio files that fell back to the default scale now infer their own (tf-01, tf-08, tf-11)
23
+ - `rhythmguard doctor` loads the Stylelint config through the project's own Stylelint (`resolveConfig`) instead of searching the config text for "rhythmguard", so every `extends`, plugin and option is resolved as `npx stylelint` resolves it. It checks that `stylelint-plugin-rhythmguard` is installed and that the installed Stylelint is in the plugin's peer range (`^16.7.0 || ^17.0.0 || ^18.0.0`). Before, with Stylelint 18 and the `init` config present but the plugin absent, doctor printed "All checks passed" and exited 0 while `npx stylelint` exited 78; it now exits 1, names the plugin and prints `npm install --save-dev "stylelint@^16.7.0 || ^17.0.0 || ^18.0.0" stylelint-plugin-rhythmguard`. `tokenPattern`, `tailwindConfigPath`, `customSyntax` and `scaleSources` are read from the resolved rule options rather than matched in the config text, and an option Stylelint rejects fails the check (dx-07, cq-11).
24
+ - In an ESLint-only project (no Stylelint installed or configured), doctor loads the ESLint config through the project's ESLint and lints one class-string file instead of checking that the config text mentions "rhythmguard". A config that cannot load (for example `eslint-plugin-rhythmguard` missing) or that does not enable `tailwind-class-use-scale` exits 1 with the install command, where it printed "All checks passed"; the Stylelint checks are reported as skipped, never as a missing install (ai-02).
25
+ - Doctor's install commands come from the same builder as the quickstart's and `init`'s: `npm install --save-dev "stylelint@<peer range>" stylelint-plugin-rhythmguard` for the Stylelint path, `npm install --save-dev eslint eslint-plugin-rhythmguard` for the ESLint path (dx-07, ai-02).
26
+ - `--fail-on-new-drift` gates drift, not token debt. It counts new off-scale, class-string, motion and missing-token findings; a new `token-opportunity` finding from `prefer-token`, a raw value a token could replace, stays in the report and the baseline and fails only with the new `--fail-on-new-token-debt` (`"failOnNewTokenDebt": true` under `audit` in `.rhythmguardrc.json`). Before, snapping `padding: 13px` to `12px`, the step the finding names, failed `--since-baseline --fail-on-new-drift`: `prefer-token` reported the on-scale `12px` as a new raw value. The off-scale literal is still gated through its `use-scale` finding. `baseline.newDriftCount` and `baseline.newTokenDebtCount` split `newFindingsCount`, the text, Markdown and GitHub summaries say `1 new (0 drift, 1 token debt)` when there is token debt, and `--format github` annotates new token debt as warnings, new drift as errors. Gate failures only go away (dx-08, ci-01)
27
+ - In the audit, `prefer-token` reads the tokens the audit resolved: the `--token-source` and `audit.tokenSources` files and the scanned stylesheets that declare spacing tokens. Its message names the token and its file, `Use var(--space-3) (tokens/tokens.json).`, through the existing template, where it said `No known token holds this value` while `rawValueMatches` listed the token. A token declared in a component block or under a media query in another stylesheet is not offered outside it. A raw fallback such as `var(--space-3, 12px)` that restates a token now known is no longer reported, so findings only go away (dx-08, ci-01, ai-04)
28
+ - A Stylelint warning whose text the audit does not read is a finding of `type: "unclassified"` with `value: null`, listed under `UNCLASSIFIED WARNINGS` in the text report, instead of an off-scale finding with `value: null`. With the audit's rule options no rule emits one; a contract test calls every message template of every rule and checks that each is read or listed as deliberately unclassified. The patterns also read `no-offscale-transform`'s `clamp()`, `min()` and `max()` positions, and no longer read a forbidden negative translation as off-scale (cq-02)
29
+
30
+ ### Added
31
+
32
+ - `rhythmguard audit --tailwind-config <file>`: with `--scale auto`, the audit reads a Tailwind v3 config's `theme.spacing` after the scanned stylesheets (`source: "tailwind"`), as the rules do with `tailwindConfigPath`. The config is loaded with `require()`, so only when the flag names it; `.rhythmguardrc.json` cannot, and an `audit.tailwindConfigPath` key there is refused, so a file in a repository (a fork's pull request, a cloned project) never makes the audit run code. A path that does not exist exits 2, like a missing token source (tf-06).
33
+ - The Claude Code skill pre-approves exactly `npx rhythmguard audit . --scale auto --format json`, the command it asks for, instead of any `npx rhythmguard audit` command, since `--tailwind-config` loads a file.
34
+ - A `tailwind` scale preset: Tailwind's default spacing theme on a 16px root. With `scale: "auto"`, a rule's `preset` is now the fallback when no tokens are found, as `configs/tailwind` uses it.
35
+ - `runDoctor({ cwd })`, `formatDoctorReport(result)` and `doctorSummary(resultOrChecks)` from `stylelint-plugin-rhythmguard/cli`, with types. `runDoctor` resolves to `{ ok, setup, issues, warnings, checks, scale, eslintScale }`; each check is `{ id, status, message, fix? }` with status `pass`, `fail`, `warn` or `skip`. It keeps no module state, prints nothing and never exits the process, so it can run after each edit or from another command; `doctorSummary` gives a few lines for another command to print (cq-11).
36
+ - `rhythmguard doctor` lints one stylesheet with the project's config and prints the spacing scale the rules check and where it comes from: the `scale` option, a preset, the default scale, or for `scale: "auto"` the token files, `.rhythmguardrc.json`, the stylesheet, the Tailwind config, a token package or the fallback preset, resolved as the rules resolve it. When the project has an ESLint config, doctor loads it through the project's ESLint, lints one class-string file, prints the scale `tailwind-class-use-scale` checks and warns when it is not the stylesheet scale, with the `scale` option that would make them agree. It warns when `.scss` files have no `customSyntax` (dx-07).
37
+ - `rhythmguard scale [dir]` prints the scale the audit checks against, its source and files, a rejected inference, the class-string scale, and the tokens that hold each step, without scanning for findings. It resolves the scale through the audit's own path: `--scale`, `--token-source`, `.rhythmguardrc.json` and `--scale auto`. `--format json` prints it for agents and scripts (`schemaVersion: "1.0"`). Like the audit, it exits 2 when a configured token source does not exist (ai-04)
38
+ - `--report-missing-tokens` (`"reportMissingTokens": true` under `audit`, `reportMissingTokens` in the API) reports each `var()` of a token that no scanned stylesheet, token source, installed token package or skipped vendored stylesheet defines as a `missing-token` finding, with its file, line, column, property and the token as `value`. It counts in totals, baselines and `--fail-on-new-drift`. Before, `var(--space-7)` with no `--space-7` anywhere appeared only in `contracts.tokens.missingTokens`, so an invented token passed every gate. Off by default in 3.x, so default findings do not grow (ai-03)
39
+
40
+ ### Fixed
41
+
42
+ - Nothing falls back in silence any more. A token source whose tokens parse but carry no length (aliases into a file that is not configured, `var()` chains, unitless values) warns with the count, three examples and why each is not a length, and the audit sets `contracts.scale.rejected` with `source: "token-sources"` instead of `rejected: null` and no warning. A `.rhythmguardrc.json` that is not valid JSON (its adopt and allow decisions were lost), a Tailwind config that throws (it read as "No known token holds this value"), a token map file that is missing or not JSON, and an invalid `tokenPattern` on a token source now say so. The warnings reach every surface: the JSON report's new root `warnings` array, the text report, the first lint message in a file (once), `doctor` and the quickstart. A repository lint rule rejects a `catch` that drops its error without a comment saying why; the 49 that remain are commented and counted by a test (tf-02, cq-05).
43
+ - The quickstart prints every source warning under the scale, finds `tokens.css`, `*.tokens.css` and Style Dictionary's `build/css/variables.css` and `dist/css/variables.css` as well as JSON token files, and when the token files it found give no scale, the pasted config points `scaleSources` at them, so each lint names why they were not read, instead of pasting a literal default (tf-12).
44
+ - Token fixes never guess and never leave a token's scope. When two tokens hold one value, `prefer-token` names both (`Use one of the tokens that hold it: var(--space-gutter) or var(--space-layout).`) and writes neither on every map source: `tokenMapFromCssCustomProperties` (on in the `tailwind` config and the playground), `tokenMapFile` and `tokenMapFromTailwindSpacing`. Before, the map kept the last token declared, so `margin: 24px` became `var(--space-layout)` while the token index named both and wrote nothing, and a `use-scale` snap followed by `prefer-token` turned `23px` into the guessed token. A token declared only under `@media`, `@supports` or `@container`, or in a component block such as `.card`, is written by `use-scale` and `no-offscale-transform` with `fixWith: "token"` and by `prefer-token` only where it is defined: under the same conditions, or inside that block. Before, `padding: 13px` became `var(--space-3)` outside the media query that defines it, which computes to no padding below the breakpoint. No rule writes a token into a `var()` fallback any more, since the fallback is what renders when the tokens are missing; the literal is written, or the value is reported and left alone. A token that is not defined where a value sits is no longer named in that value's message either. The findings and the message templates are unchanged (css-08, fix-06, fix-02)
45
+
46
+ ## [3.19.0] - 2026-11-09
47
+
48
+ ### Changed
49
+
50
+ - The agent packs follow each tool's format and audit against the project's scale. The audit command in them is `npx rhythmguard audit . --scale auto --format json`; without `--scale auto` it checked a built-in scale, and an agent snapped correct 40px, 48px and 64px values. A new line tells agents never to invent a token name and where defined and missing tokens are listed. The Claude Code skill gains `when_to_use`, `paths` (it loads for stylesheet and component files) and `allowed-tools` for `npx rhythmguard audit` only: Stylelint and ESLint load JavaScript configs and plugins, and `fix` and `init` write files, so those runs keep the user's approval. The Cursor rule is attached by its globs (`alwaysApply: false`; with `true` Cursor ignored the globs and loaded it into every chat). Copilot gets its own `.github/instructions/rhythmguard.instructions.md` with `applyTo` globs, and `init --agents copilot` removes the block that older versions appended to `.github/copilot-instructions.md`. A contract test checks each pack's frontmatter against the keys its tool documents.
51
+ - The GitHub Action, `PetriLahdelma/rhythmguard-action@v1`, is at 1.1.0. Since 3.16.0 it had failed on every project with a stylesheet: it ran the plugin package, which no longer brings Stylelint. It now runs the `rhythmguard` package at `^3`, and a new `require-baseline` input fails the job when the baseline file is missing.
52
+
53
+ - A configured token source that does not exist (`--token-source` or `audit.tokenSources`) makes `rhythmguard audit` exit 2, after printing its report, with `Token source not found: <path>` on stderr. Before, it exited 0 against whichever scale came next, so a typo in a CI path passed silently.
54
+ - A run that read no stylesheet and no template file says "Nothing was audited" and why (no matching files, or stylesheets skipped for Stylelint, postcss-scss, `.stylelintignore`, vendored code or parse errors), in the text and Markdown reports, instead of "No issues found". The quickstart's hint for an empty directory no longer names a `./src` that may not exist. Cleanliness, which counts no files in that case, and the exit code under a gate change in 4.0.
55
+
56
+ - `--format github` puts the summary notice first, and with a baseline it annotates only the new findings, as errors. GitHub shows 10 annotations of each type per step and drops the rest without saying so, so the output stops at 10 per type and adds a notice with the number left out. Before, every finding was a warning, and the one new line in a pull request could be annotation 4,695 of 5,987. Above about 100,000 findings the renderer also overflowed the stack; it no longer does.
57
+ - `--format markdown` starts with the new findings when there is a baseline (up to 25, then a count) and lists at most five files per row. On a 300-stylesheet project the report drops from 64 KB, just under GitHub's 65,536-character comment limit, to 6 KB. Its next actions propose `--plan` and `rhythmguard fix --value` instead of a blanket autofix.
58
+
59
+ - The quickstart's and `init`'s next steps work when pasted. Before, four of five first-run stacks failed at the quickstart's own next command. Now:
60
+ - Above each config the quickstart prints the install line that config needs: Stylelint at the plugin's peer range, `stylelint-config-tailwindcss` for the `tailwind` config, `postcss-scss` when it found SCSS, and `eslint eslint-plugin-rhythmguard`, plus `typescript-eslint` when it found TypeScript.
61
+ - A project with SCSS gets `"customSyntax": "postcss-scss"`.
62
+ - In a project with `.ts` or `.tsx` files, the ESLint snippet lints them through typescript-eslint's parser and imports `eslint-plugin-rhythmguard`, the package the install line names. Before, the snippet linted only JavaScript files, so it found nothing in a TypeScript project.
63
+ - The Stylelint glob comes from where the stylesheets are (`styles/**/*.scss`, not `**/*.css`).
64
+ - `init` writes the same syntax and prints the same install line and glob.
65
+ - The `rhythmguard` package depends on `postcss-scss`, so `npx rhythmguard` audits SCSS on first contact instead of skipping it.
66
+ - The text report's last lines repeat the run's own directory and scale flags, so the next command uses the same scale. They propose `--plan` (one decision per off-scale value) and `rhythmguard fix --value <px> --to <step or token>` instead of `npx stylelint --fix`, which snaps every value without a review. The quickstart's next steps include `--plan` too.
67
+ - `docs/FRAMEWORKS.md` says that component `<style>` blocks in Vue, Svelte and Astro are not tested yet and are not in the audit's numbers.
68
+
69
+ - `rhythmguard audit` and the quickstart work in a project without Stylelint. Installing `eslint-plugin-rhythmguard` puts the plugin's `rhythmguard` command on the path without Stylelint, and the audit used to stop at the first stylesheet, so `npx rhythmguard` and the agent pack's audit command failed in every ESLint-only Tailwind app. Now the audit reads the class strings, lists the stylesheets it could not read as "Stylesheets not audited" with `npm install --save-dev stylelint` (`scanned.stylelintMissing` in JSON), and leaves them out of cleanliness and the baseline. It exits 0, except that `--max-findings`, `--min-cleanliness` and `--fail-on-new-drift` fail and say why, since a gate must not pass on a partial read. The quickstart prints the ESLint config first in that case, and the agent packs say to run `npx eslint .` there.
70
+
71
+ - `tailwindConfigPath` loads the config with `require()` only. The fallback that imported it in a child `node` process with a 5-second timeout is gone: `require()` loads CommonJS and ES module configs alike on every supported Node, so it ran only for a config that uses top-level await, and no test exercised it. Such a config is no longer read; point `scaleSources` at the CSS it builds instead.
72
+ - `SECURITY.md` says what the packages do on your machine: no network requests and no telemetry (a new contract test fails the build otherwise), no install scripts, which files they read, the one config they run as code and only when asked, `git` as the only program they start, and which commands write files. The rule docs say the same next to `tailwindConfigPath`.
73
+ - The workflows pin every action by commit digest, give the token read-only permissions by default, and do not leave credentials in the checkout; the publish job pins npm to the version the last green publish ran. A `renovate.json` keeps action digests current and leaves the benchmark trees, whose tools are pinned on purpose, to be bumped by hand.
74
+
75
+ - The release verify matrix and the post-publish smoke run on GitHub-hosted runners by default (`RELEASE_ON_FARM=true` moves them back to the self-hosted farm), and the release verify now runs the typecheck. `node scripts/release/prepare.mjs X.Y.Z` makes the release edits and runs the local gate, and refuses a release within 24 hours of the last one. Pull requests get a GitHub-hosted fast gate when the repository variable `HOSTED_GATE` is set, as a trial; the local gate stays the merge gate. Node 20, end of life since 2026-04-30 but still the engines floor until 4.0, keeps one CI row, the full suite on Stylelint 17. A non-blocking Windows job runs on pushes to `main`, and the weekly job checks the newest Stylelint, ESLint and Oxlint separately.
76
+
9
77
  ## [3.18.0] - 2026-11-05
10
78
 
11
79
  ### Changed
package/CONTRIBUTING.md CHANGED
@@ -38,7 +38,7 @@ npm ci
38
38
  npm test
39
39
  ```
40
40
 
41
- Node 20.19 or newer; `.nvmrc` pins 22 for development, so `nvm use` picks it up. A [dev container](./.devcontainer/devcontainer.json) gives the same setup in Codespaces or VS Code. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about fifteen seconds. They are grouped by what they prove:
41
+ Node 20.19 or newer; `.nvmrc` pins 24 for development, so `nvm use` picks it up. A [dev container](./.devcontainer/devcontainer.json) gives the same setup in Codespaces or VS Code. No build step; the source runs as is. Tests use `node --test` through `scripts/test.mjs` and take about fifteen seconds. They are grouped by what they prove:
42
42
 
43
43
  | Folder | Proves | Run one |
44
44
  | --- | --- | --- |
@@ -74,7 +74,7 @@ npm run build:playground # after changing anything under src/ the rules us
74
74
  npm run bench:agents -- --dry-run --limit 4 # the agent eval pipeline, no API key needed
75
75
  ```
76
76
 
77
- The local gate runs on whatever Node you have installed; CI runs Node 20 and 22 against Stylelint 16.7.0, 16 and 17, Node 22, 24 and 26 against Stylelint 18, the ESLint companion rules on ESLint 9, and once a week the full suite against the newest Stylelint (`next` while a major is in prerelease, else `latest`). Node 20.19 is the floor, so avoid features that arrived in Node 21 or later. Glob patterns for `node --test` were one such feature, and they took a release run down.
77
+ The local gate runs on whatever Node you have installed; CI runs Node 22 against Stylelint 16.7.0, 16, 17 and 18, Node 24 and 26 against 18, Node 20 against Stylelint 17 (the full suite, since Node 20.19 is still the engines floor), the ESLint companion rules on ESLint 9, a non-blocking Windows job on pushes to `main`, and once a week the newest Stylelint, ESLint and Oxlint. Pull requests from forks get one GitHub-hosted job (lint, typecheck, tests); with the repository variable `HOSTED_GATE` set, same-repo pull requests get the same job as an advisory fast gate and the farm matrix runs after merge. The local gate is the merge gate either way. Node 20.19 is the floor, so avoid features that arrived in Node 21 or later. Glob patterns for `node --test` were one such feature, and they took a release run down.
78
78
 
79
79
  If your shell's npm registry is overridden by a corporate `.npmrc`, add `--registry https://registry.npmjs.org` to `npm ci` and prefix `test:pack-smoke` with `npm_config_registry=https://registry.npmjs.org`.
80
80
 
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  Nobody chose 13px. Rhythmguard catches off-scale spacing in CSS and Tailwind class strings, tells you the nearest steps on your scale, and snaps to them or to your tokens when you ask.
8
8
 
9
9
  [![CI](https://img.shields.io/github/actions/workflow/status/petrilahdelma/stylelint-plugin-rhythmguard/ci.yml?branch=main&label=ci)](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/actions/workflows/ci.yml)
10
- [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3180)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
10
+ [![npm version](https://img.shields.io/npm/v/stylelint-plugin-rhythmguard?label=npm&color=1f6feb&r=3200)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
11
11
  [![npm downloads](https://img.shields.io/npm/dm/stylelint-plugin-rhythmguard.svg)](https://www.npmjs.com/package/stylelint-plugin-rhythmguard)
12
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-white.svg)](./LICENSE)
13
13
 
@@ -21,7 +21,7 @@ What it is not: it does not check colors or hex values, and the Stylelint rules
21
21
  npx rhythmguard
22
22
  ```
23
23
 
24
- No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste. This is the whole run on Bootstrap's `v6-dev` branch, unedited:
24
+ No install, no config. It detects your stack and token files, infers your spacing scale from your own tokens, audits the current directory, and prints the exact `.stylelintrc.json` (and ESLint snippet for Tailwind) to paste, with the `.rhythmguardrc.json` that makes a bare `npx rhythmguard audit .` use the same scale. This is the whole run on Bootstrap's `v6-dev` branch, unedited:
25
25
 
26
26
  <p align="center">
27
27
  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/quickstart.gif?v=1" width="100%" alt="Terminal recording: npx stylelint-plugin-rhythmguard on Bootstrap v6-dev detects the stack, infers the 13-step spacing scale from scss/_config.scss, reports 20 off-scale values in CSS and prints a .stylelintrc.json to paste" />
@@ -103,7 +103,7 @@ npx rhythmguard audit ./src --format github
103
103
 
104
104
  The audit scans CSS declarations, Tailwind class strings and your token contract, prints a scale-cleanliness score, and supports baselines so legacy codebases can gate only new drift. Formats: text, Markdown, JSON 2.0, HTML, GitHub Actions annotations, and a shields.io badge document for your README. Full reference in [docs/AUDIT.md](docs/AUDIT.md), rollout recipe and the badge workflow in [docs/CI_ADOPTION.md](docs/CI_ADOPTION.md). In GitHub Actions, [`PetriLahdelma/rhythmguard-action@v1`](https://github.com/PetriLahdelma/rhythmguard-action) runs the audit, annotates the diff, comments on the pull request and fails on new drift in one step.
105
105
 
106
- `npx rhythmguard audit ./src --plan` turns the report into a proposed `decisions` section (adopt a value, allow it, or snap it), and `npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write` executes one decision as one reviewable change; see [decisions](docs/AUDIT.md#decisions). `npx rhythmguard init` writes a starter config for your stack, and `init --agents all` installs the coding-agent instructions. `npx rhythmguard doctor` checks the setup.
106
+ `npx rhythmguard audit ./src --plan` turns the report into a proposed `decisions` section (adopt a value, allow it, or snap it), and `npx rhythmguard fix ./src --value 10px --to "var(--space-sm)" --write` executes one decision as one reviewable change; see [decisions](docs/AUDIT.md#decisions). `npx rhythmguard scale` prints the scale the audit checks against, where it came from and the token for each step. `npx rhythmguard init` writes the config the quickstart prints, showing a diff before it replaces one, and `init --agents all` installs the coding-agent instructions. `npx rhythmguard doctor` checks the setup: it loads your Stylelint and ESLint configs as the linters do, lints one file with each, prints the spacing scale and where it comes from, and gives the exact install command for anything missing.
107
107
 
108
108
  ## Guides
109
109
 
@@ -144,7 +144,7 @@ The two do not overlap. Rhythmguard reports the `13px` padding and the `17px` he
144
144
 
145
145
  ## Compatibility
146
146
 
147
- Stylelint 16.7 to 18. The floor is 16.7.0 because Stylelint reads a rule's fix callback from that version on; on 16.0 to 16.6 `--fix` changed nothing. Node 20.19 or newer; Node 20 itself is end of life, and 4.0 raises the floor to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)). Stylelint 18 needs Node 22.22, 24.15 or 26, and on an older Node npm installs Stylelint 17 for `npx rhythmguard`. The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9 and 10, and is tested in CI on Oxlint 1.88.0. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `stylelint` is a peer you need only for the Stylelint rules and the stylesheet audit, so an ESLint-only project installs without it, and `npx rhythmguard` brings its own; `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers (`stylelint-plugin-logical-css` itself still peers on Stylelint 17 or older). CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.7.0, 16.x and 17.x, and Node 22, 24 and 26 against 18.x; a weekly job runs the suite against the latest Stylelint. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
147
+ Stylelint 16.7 to 18. The floor is 16.7.0 because Stylelint reads a rule's fix callback from that version on; on 16.0 to 16.6 `--fix` changed nothing. Node 20.19 or newer; Node 20 itself is end of life, and 4.0 raises the floor to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)). Stylelint 18 needs Node 22.22, 24.15 or 26, and on an older Node npm installs Stylelint 17 for `npx rhythmguard`. The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9 and 10, and is tested in CI on Oxlint 1.88.0. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `stylelint` is a peer you need only for the Stylelint rules and the stylesheet audit, so an ESLint-only project installs without it, and `npx rhythmguard` brings its own; `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers (`stylelint-plugin-logical-css` itself still peers on Stylelint 17 or older). CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 22 against Stylelint 16.7.0, 16.x, 17.x and 18.x, Node 24 and 26 against 18.x, and Node 20 against 17.x; a weekly job runs the suite against the newest Stylelint, ESLint and Oxlint. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
148
148
 
149
149
  ### Stylelint 18's custom-property rule
150
150
 
package/SECURITY.md CHANGED
@@ -8,6 +8,20 @@
8
8
  | 2.x | Security fixes only until 2027-03-01 |
9
9
  | < 2.0 | No, upgrade to 3.x |
10
10
 
11
+ ## What this package does on your machine
12
+
13
+ This applies to all three packages: `stylelint-plugin-rhythmguard`, `rhythmguard` and `eslint-plugin-rhythmguard`.
14
+
15
+ - **No network requests and no telemetry.** Nothing in the packages opens a connection, and nothing is collected or sent. `test/contracts/no-network.test.js` fails the build if any source file imports a network module or calls `fetch`.
16
+ - **No install scripts.** None of the three packages runs code when it is installed.
17
+ - **It reads** the stylesheets and class-string files it lints or audits, the token files and packages you point it at (`scaleSources`, `tokenMapFile`, `--token-source`, `.rhythmguardrc.json`), and installed design-token packages that your `package.json` lists directly.
18
+ - **It runs one file of yours as code, and only when you ask.** With `tailwindConfigPath` set in a Stylelint config, the rules load that Tailwind config with `require()` to read `theme.spacing`; `rhythmguard audit` does the same only with `--tailwind-config <file>` on the command line, never from `.rhythmguardrc.json`, so a file in a repository cannot make the audit run code. A config that uses top-level await is not loaded. To avoid running it at all, point `scaleSources` at the CSS it builds instead.
19
+ - **`rhythmguard doctor` loads your linter configs as the linters do.** It resolves your Stylelint config through your installed Stylelint and, when there is one, your ESLint config through your installed ESLint, and lints one file with each, so any JavaScript config or plugin they name runs, as it does when you run `npx stylelint` or `npx eslint`. `rhythmguard audit` loads neither.
20
+ - **It starts one program: `git`,** and only for `rhythmguard audit --since` and `--staged`, to list changed files and read staged contents. The source test above allows no other process.
21
+ - **It writes files only when you ask:** `stylelint --fix` and `eslint --fix` through the host linter, `rhythmguard fix --write`, `audit --write-baseline` and `audit --output <file>`, and `rhythmguard init`, which asks before writing a config or agent files.
22
+ - **Provenance.** Every release is published from this repository's `release.yml` through npm trusted publishing, with no npm token anywhere, and carries an npm provenance attestation. Check it with `npm audit signatures` in a project that installs the package, or `npm view stylelint-plugin-rhythmguard dist.attestations`.
23
+ - **CI.** The workflows pin every action by commit digest, give the token read-only permissions unless a job needs more, and do not leave credentials in the checkout. The CI result collector in `.github/scripts/report-ci.sh` reports this repository's own job results to the maintainer's dashboard; it is not part of any package.
24
+
11
25
  ## Reporting a Vulnerability
12
26
 
13
27
  Please do **not** open public GitHub issues for security reports.
@@ -1,14 +1,27 @@
1
1
  ---
2
2
  name: rhythmguard
3
3
  description: Keep CSS and Tailwind spacing on the project scale. Use when writing or changing CSS, SCSS, CSS Modules or Tailwind class strings, and before finishing any such change.
4
+ when_to_use: Adding or changing padding, margin, gap, inset or other spacing in a stylesheet or a class string; reviewing a diff that does.
5
+ allowed-tools: Bash(npx rhythmguard audit . --scale auto --format json)
6
+ paths:
7
+ - "**/*.css"
8
+ - "**/*.scss"
9
+ - "**/*.jsx"
10
+ - "**/*.tsx"
11
+ - "**/*.vue"
12
+ - "**/*.svelte"
13
+ - "**/*.astro"
14
+ - "**/*.html"
4
15
  ---
5
16
 
6
17
  ## Spacing scale
7
18
 
8
19
  This project enforces its spacing scale with stylelint-plugin-rhythmguard.
9
20
 
10
- - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
21
+ - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --scale auto --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding. Without `--scale auto` the audit checks a built-in scale, not this project's.
22
+ - In a project with ESLint or Oxlint and no Stylelint, the audit reads class strings only and lists the stylesheets it skipped; run `npx eslint .` (or `npx oxlint`) as well, and do not install Stylelint unless the task asks for it.
11
23
  - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
24
+ - Never invent a token name. Use a token only if the project defines it: the audit lists them under `contracts.tokens.definedTokens`, and any `var()` it cannot find under `contracts.tokens.missingTokens`. A `var()` that points at nothing renders no spacing at all.
12
25
  - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
13
26
  - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
14
27
  - Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
@@ -1,9 +1,15 @@
1
+ ---
2
+ applyTo: "**/*.css,**/*.scss,**/*.jsx,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.html"
3
+ ---
4
+
1
5
  ## Spacing scale
2
6
 
3
7
  This project enforces its spacing scale with stylelint-plugin-rhythmguard.
4
8
 
5
- - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
9
+ - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --scale auto --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding. Without `--scale auto` the audit checks a built-in scale, not this project's.
10
+ - In a project with ESLint or Oxlint and no Stylelint, the audit reads class strings only and lists the stylesheets it skipped; run `npx eslint .` (or `npx oxlint`) as well, and do not install Stylelint unless the task asks for it.
6
11
  - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
12
+ - Never invent a token name. Use a token only if the project defines it: the audit lists them under `contracts.tokens.definedTokens`, and any `var()` it cannot find under `contracts.tokens.missingTokens`. A `var()` that points at nothing renders no spacing at all.
7
13
  - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
8
14
  - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
9
15
  - Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
@@ -1,15 +1,17 @@
1
1
  ---
2
2
  description: Spacing scale rules enforced by stylelint-plugin-rhythmguard
3
- globs: ["**/*.css", "**/*.scss", "**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html"]
4
- alwaysApply: true
3
+ globs: **/*.css, **/*.scss, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html
4
+ alwaysApply: false
5
5
  ---
6
6
 
7
7
  ## Spacing scale
8
8
 
9
9
  This project enforces its spacing scale with stylelint-plugin-rhythmguard.
10
10
 
11
- - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding.
11
+ - Before finishing any change to CSS or to Tailwind class strings, run `npx rhythmguard audit . --scale auto --format json` (or `npx stylelint "**/*.css"` if a config exists) and fix every `off-scale` finding. Without `--scale auto` the audit checks a built-in scale, not this project's.
12
+ - In a project with ESLint or Oxlint and no Stylelint, the audit reads class strings only and lists the stylesheets it skipped; run `npx eslint .` (or `npx oxlint`) as well, and do not install Stylelint unless the task asks for it.
12
13
  - A finding names the value and the two nearest on-scale values. Prefer the design token for that value when one exists; otherwise use the nearest on-scale value. Never invent a new spacing value.
14
+ - Never invent a token name. Use a token only if the project defines it: the audit lists them under `contracts.tokens.definedTokens`, and any `var()` it cannot find under `contracts.tokens.missingTokens`. A `var()` that points at nothing renders no spacing at all.
13
15
  - Do not use `--fix` on spacing findings unless the task says so. Snapping a value can change layout; choose the value deliberately.
14
16
  - Values of one pixel or less (hairlines) and percentages are allowed and are not findings.
15
17
  - Tailwind arbitrary spacing values such as `p-[13px]` are findings too. The finding names the two utility classes to choose from (`p-3` or `p-4`); write one of those, not another arbitrary value.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stylelint-plugin-rhythmguard",
3
- "version": "3.18.0",
3
+ "version": "3.20.0",
4
4
  "description": "Nobody chose 13px. Catches off-scale spacing in CSS and Tailwind class strings and snaps it to your scale or tokens. Stylelint rules, an ESLint companion, and an audit CLI.",
5
5
  "bin": {
6
6
  "rhythmguard": "src/cli/index.js"
@@ -194,7 +194,7 @@
194
194
  "stylelint": "^17.0.0",
195
195
  "stylelint-config-tailwindcss": "^1.0.1",
196
196
  "stylelint-plugin-logical-css": "^2.0.2",
197
- "stylelint-scales": "^5.0.0",
197
+ "stylelint-scales": "^6.0.0",
198
198
  "typescript": "^7.0.0"
199
199
  },
200
200
  "engines": {
package/src/audit/args.js CHANGED
@@ -46,8 +46,10 @@ const OPTIONS = [
46
46
  apply: (p, raw) => { p.writeBaseline = true; setFrom(p, 'writeBaseline'); if (raw !== undefined) { p.baselinePath = parsePathOption(raw, '--write-baseline'); setFrom(p, 'baselinePath'); } } },
47
47
  { flag: '--since-baseline', kind: 'optional', value: '[file]', help: 'Compare current findings against a baseline',
48
48
  apply: (p, raw) => { p.sinceBaseline = true; setFrom(p, 'sinceBaseline'); if (raw !== undefined) { p.baselinePath = parsePathOption(raw, '--since-baseline'); setFrom(p, 'baselinePath'); } } },
49
- { flag: '--fail-on-new-drift', kind: 'flag', help: 'Exit 1 when --since-baseline finds new drift',
49
+ { flag: '--fail-on-new-drift', kind: 'flag', help: ['Exit 1 when --since-baseline finds new drift: off-scale, class-string,', 'motion and missing-token findings, not token debt'],
50
50
  apply: (p) => { p.failOnNewDrift = true; setFrom(p, 'failOnNewDrift'); } },
51
+ { flag: '--fail-on-new-token-debt', kind: 'flag', help: ['Exit 1 when --since-baseline finds new token debt: raw values', 'prefer-token says a token could replace'],
52
+ apply: (p) => { p.failOnNewTokenDebt = true; setFrom(p, 'failOnNewTokenDebt'); } },
51
53
  { flag: '--max-findings', kind: 'value', value: '<number>', help: 'Exit 1 when total findings exceed this count',
52
54
  apply: (p, raw) => { p.maxFindings = parseNonNegativeInteger(raw, '--max-findings'); setFrom(p, 'maxFindings'); } },
53
55
  { flag: '--min-cleanliness', kind: 'value', value: '<percent>', help: 'Exit 1 when scale cleanliness is lower than this percent',
@@ -57,6 +59,8 @@ const OPTIONS = [
57
59
  { flag: '--staged', kind: 'flag', help: 'Scan only staged files', apply: (p) => { p.staged = true; setFrom(p, 'staged'); } },
58
60
  { flag: '--check-math-bounds', kind: 'flag', help: 'Check clamp() minimum and maximum and min()/max() arguments against the scale',
59
61
  apply: (p) => { p.checkMathBounds = true; setFrom(p, 'checkMathBounds'); } },
62
+ { flag: '--report-missing-tokens', kind: 'flag', help: ['Report each var() of a token nothing defines as a missing-token', 'finding (counted in totals, baselines and --fail-on-new-drift)'],
63
+ apply: (p) => { p.reportMissingTokens = true; setFrom(p, 'reportMissingTokens'); } },
60
64
  { flag: '--include-motion', kind: 'flag', help: 'Include opt-in motion duration/easing drift',
61
65
  apply: (p) => { p.includeMotion = true; setFrom(p, 'includeMotion'); } },
62
66
  { flag: '--include-non-authored', kind: 'flag', help: ['Audit vendored, test, generated, minified and built stylesheets', '(skipped by default: vendor/, tests/, generated/, *.min.css, one-line CSS over 5 KB)'],
@@ -69,8 +73,10 @@ const OPTIONS = [
69
73
  apply: (p, raw) => { p.tokenKind = normalizeTokenKind(raw); setFrom(p, 'tokenKind'); } },
70
74
  { flag: '--token-candidate-min-count', kind: 'value', value: '<n>', help: 'Minimum repeated raw value count for token candidates (default: 2)',
71
75
  apply: (p, raw) => { p.tokenCandidateMinCount = parsePositiveInteger(raw, '--token-candidate-min-count'); setFrom(p, 'tokenCandidateMinCount'); } },
72
- { flag: '--scale', kind: 'value', value: '<values|auto>', help: ['Comma-separated scale values (default: 0,4,8,12,16,24,32);', 'auto infers the scale from token sources, then --space-*/--spacing-*', 'custom properties and Sass variables in scanned CSS/SCSS, then', 'installed design-token packages, and reports where it came from'],
76
+ { flag: '--scale', kind: 'value', value: '<values|auto>', help: ['Comma-separated scale values (default: 0,4,8,12,16,24,32,40,48,64);', 'auto infers the scale from token sources, then --space-*/--spacing-*', 'custom properties and Sass variables in scanned CSS/SCSS, then', '--tailwind-config, then installed design-token packages,', 'and reports where it came from'],
73
77
  apply: (p, raw) => { p.scale = parseScale(raw); setFrom(p, 'scale'); } },
78
+ { flag: '--tailwind-config', kind: 'value', value: '<file>', help: ['Tailwind v3 config whose theme.spacing --scale auto reads', '(loaded with require(), so it runs as code; only when given)'],
79
+ apply: (p, raw) => { p.tailwindConfigPath = parsePathOption(raw, '--tailwind-config'); setFrom(p, 'tailwindConfigPath'); } },
74
80
  { flag: '--base-font-size', kind: 'value', value: '<number>', help: 'px base for rem/em conversion (default: 16)',
75
81
  apply: (p, raw) => { p.baseFontSize = parseBaseFontSize(raw); setFrom(p, 'baseFontSize'); } },
76
82
  { flag: '--help', alias: '-h', kind: 'flag', help: 'Show this help message', apply: (p) => { p.help = true; } },
@@ -78,9 +84,9 @@ const OPTIONS = [
78
84
 
79
85
  const HELP_COLUMN = 33;
80
86
 
81
- function renderHelp() {
82
- const lines = ['Usage: rhythmguard audit <dir> [options]', '', 'Options:'];
83
- for (const option of OPTIONS) {
87
+ function renderOptionLines(options) {
88
+ const lines = [];
89
+ for (const option of options) {
84
90
  const label = ` ${option.flag}${option.value ? ` ${option.value}` : ''}`;
85
91
  const help = Array.isArray(option.help) ? option.help : [option.help];
86
92
  lines.push(`${label.padEnd(HELP_COLUMN)}${label.length >= HELP_COLUMN ? ' ' : ''}${help[0]}`);
@@ -88,6 +94,11 @@ function renderHelp() {
88
94
  lines.push(`${''.padEnd(HELP_COLUMN)}${extra}`);
89
95
  }
90
96
  }
97
+ return lines;
98
+ }
99
+
100
+ function renderHelp() {
101
+ const lines = ['Usage: rhythmguard audit <dir> [options]', '', 'Options:', ...renderOptionLines(OPTIONS)];
91
102
  lines.push(
92
103
  '',
93
104
  'Scans .css files, and .scss files when postcss-scss is installed. Reports drift by',
@@ -100,12 +111,18 @@ function renderHelp() {
100
111
 
101
112
  const HELP = renderHelp();
102
113
 
103
- function findOption(arg) {
104
- return OPTIONS.find((option) => option.flag === arg || option.alias === arg) || null;
114
+ function findOptionIn(arg, options = OPTIONS) {
115
+ return options.find((option) => option.flag === arg || option.alias === arg) || null;
105
116
  }
106
117
 
107
- function parseArgs(argv) {
118
+ /**
119
+ * Parse audit arguments. `options` narrows the accepted flags to a subset of
120
+ * OPTIONS, for a command such as `rhythmguard scale` that resolves the scale
121
+ * the way the audit does and takes the audit's flags for it.
122
+ */
123
+ function parseArgs(argv, options = OPTIONS) {
108
124
  const parsed = createDefaultAuditOptions();
125
+ const findOption = (arg) => findOptionIn(arg, options);
109
126
 
110
127
  for (let index = 0; index < argv.length; index++) {
111
128
  const arg = argv[index];
@@ -155,6 +172,10 @@ function parseArgs(argv) {
155
172
  throw new Error('--fail-on-new-drift requires --since-baseline.');
156
173
  }
157
174
 
175
+ if (parsed.failOnNewTokenDebt && !parsed.sinceBaseline) {
176
+ throw new Error('--fail-on-new-token-debt requires --since-baseline.');
177
+ }
178
+
158
179
  return parsed;
159
180
  }
160
181
 
@@ -299,6 +320,7 @@ function parseBaseFontSize(raw) {
299
320
  module.exports = {
300
321
  OPTIONS,
301
322
  HELP,
323
+ renderOptionLines,
302
324
  parseArgs,
303
325
  parseBaseFontSize,
304
326
  parseIgnorePatterns,
@@ -103,11 +103,16 @@ function applyBaselineComparison(report, baselinePath, scopeInput) {
103
103
  const newFindings = currentFindings.filter((finding) => !baselineKeys.has(currentKeys.get(finding)));
104
104
  const resolvedFindings = entries.filter((entry) => !currentKeySet.has(entry.key) && countsAsResolved(scope, entry.file));
105
105
 
106
+ const newTokenDebtCount = newFindings.filter(isTokenDebtFinding).length;
106
107
  report.baseline = {
107
108
  baselineFindings: baselineFindings.length,
108
109
  file: formatPath(resolvedPath),
110
+ // What --fail-on-new-drift counts: every new finding but token debt.
111
+ newDriftCount: newFindings.length - newTokenDebtCount,
109
112
  newFindings,
110
113
  newFindingsCount: newFindings.length,
114
+ // What --fail-on-new-token-debt counts.
115
+ newTokenDebtCount,
111
116
  resolvedFindingsCount: resolvedFindings.length,
112
117
  };
113
118
  report.summary.newFindings = newFindings.length;
@@ -230,6 +235,18 @@ function legacyWriterDirectory(directory, scanRoot) {
230
235
  return path.resolve(scanRoot, ...segments.map(() => '..'));
231
236
  }
232
237
 
238
+ /**
239
+ * Token debt: a raw value prefer-token says could be a token. It is not
240
+ * drift. On a scale value it is what the off-scale finding asked for: 13px
241
+ * snapped to 12px is a fix, and a gate that failed it rejected the fix the
242
+ * audit recommended (dx-08, ci-01). On an off-scale value it sits at the same
243
+ * position as the use-scale finding, which the drift gate already counts.
244
+ * --fail-on-new-drift leaves it out; --fail-on-new-token-debt gates it.
245
+ */
246
+ function isTokenDebtFinding(finding) {
247
+ return Boolean(finding) && finding.type === 'token-opportunity';
248
+ }
249
+
233
250
  function getAllFindings(report) {
234
251
  return [
235
252
  ...report.findings.css,
@@ -297,6 +314,14 @@ function createLegacyFindingKey(finding) {
297
314
 
298
315
  function getAuditFailures(report, parsed) {
299
316
  const failures = [];
317
+ const gated = parsed.maxFindings !== null || parsed.minCleanliness !== null || parsed.failOnNewDrift || parsed.failOnNewTokenDebt === true;
318
+ const missing = (report.scanned && report.scanned.stylelintMissing) || 0;
319
+
320
+ // Without Stylelint the stylesheets were not audited, so no gate can pass on
321
+ // what was read: say so and fail, rather than pass on class strings alone.
322
+ if (gated && missing > 0) {
323
+ failures.push(`${missing} stylesheet(s) were not audited because Stylelint is not installed (npm install --save-dev stylelint), so the gate cannot pass`);
324
+ }
300
325
 
301
326
  if (parsed.maxFindings !== null && report.totalWarnings > parsed.maxFindings) {
302
327
  failures.push(`total findings ${report.totalWarnings} exceeds --max-findings ${parsed.maxFindings}`);
@@ -308,13 +333,29 @@ function getAuditFailures(report, parsed) {
308
333
  failures.push(`scale cleanliness ${report.scaleCleanliness}% is below --min-cleanliness ${parsed.minCleanliness}%`);
309
334
  }
310
335
 
311
- if (parsed.failOnNewDrift && report.baseline && report.baseline.newFindingsCount > 0) {
312
- failures.push(`new drift found: ${report.baseline.newFindingsCount} finding(s) not present in baseline`);
336
+ // Token debt is not drift (see isTokenDebtFinding); it fails only with --fail-on-new-token-debt.
337
+ const comparison = report.baseline || null;
338
+ const newDrift = comparison ? countNew(comparison, 'newDriftCount', (finding) => !isTokenDebtFinding(finding)) : 0;
339
+ if (parsed.failOnNewDrift && newDrift > 0) {
340
+ failures.push(`new drift found: ${newDrift} finding(s) not present in baseline`);
341
+ }
342
+
343
+ const newTokenDebt = comparison ? countNew(comparison, 'newTokenDebtCount', isTokenDebtFinding) : 0;
344
+ if (parsed.failOnNewTokenDebt === true && newTokenDebt > 0) {
345
+ failures.push(`new token debt found: ${newTokenDebt} raw value(s) a token could replace, not present in baseline`);
313
346
  }
314
347
 
315
348
  return failures;
316
349
  }
317
350
 
351
+ /** A count from the comparison, or worked out from its new findings when an older caller built it without one. */
352
+ function countNew(comparison, key, predicate) {
353
+ if (Number.isInteger(comparison[key])) {
354
+ return comparison[key];
355
+ }
356
+ return (comparison.newFindings || []).filter(predicate).length;
357
+ }
358
+
318
359
  module.exports = {
319
360
  BASELINE_FORMAT_VERSION,
320
361
  applyBaselineComparison,
@@ -323,6 +364,7 @@ module.exports = {
323
364
  createLegacyFindingKey,
324
365
  getAllFindings,
325
366
  getAuditFailures,
367
+ isTokenDebtFinding,
326
368
  legacyWriterDirectory,
327
369
  writeBaseline,
328
370
  };
@@ -169,6 +169,7 @@ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], includeNonAut
169
169
  try {
170
170
  parsed = parseStylesheet(filePath, source);
171
171
  } catch {
172
+ // Not parseable: listed in `skipped` with the reason.
172
173
  skipped.push({ file: formatPath(filePath), reason: 'could not parse' });
173
174
  continue;
174
175
  }
@@ -201,6 +202,7 @@ function writableRealPath(filePath, rootDir, realRoot) {
201
202
  }
202
203
  realPath = fs.realpathSync(filePath);
203
204
  } catch {
205
+ // A path that cannot be resolved is not a file to rewrite.
204
206
  return null;
205
207
  }
206
208
  const expected = path.join(realRoot, path.relative(rootDir, filePath));
@@ -57,6 +57,11 @@ function loadAuditConfig(parsed) {
57
57
  if (!audit || typeof audit !== 'object' || Array.isArray(audit)) {
58
58
  throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: "audit" must be an object.`);
59
59
  }
60
+ // A file in the repository must never make the audit run code: a Tailwind
61
+ // config is loaded with require(), so only --tailwind-config names one.
62
+ if (audit.tailwindConfigPath !== undefined) {
63
+ throw new Error(`Invalid Rhythmguard config ${parsed.configPath}: audit.tailwindConfigPath is not read from a config file, because loading a Tailwind config runs it. Pass --tailwind-config on the command line.`);
64
+ }
60
65
 
61
66
  return {
62
67
  audit,
@@ -112,6 +117,8 @@ function applyAuditConfig(parsed, configResult) {
112
117
  applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
113
118
  applyConfigScalar(next, audit, cliOptions, 'includeNonAuthored', 'includeNonAuthored', parseBooleanOption);
114
119
  applyConfigScalar(next, audit, cliOptions, 'checkMathBounds', 'checkMathBounds', parseBooleanOption);
120
+ applyConfigScalar(next, audit, cliOptions, 'failOnNewTokenDebt', 'failOnNewTokenDebt', parseBooleanOption);
121
+ applyConfigScalar(next, audit, cliOptions, 'reportMissingTokens', 'reportMissingTokens', parseBooleanOption);
115
122
  applyConfigScalar(next, audit, cliOptions, 'scales', 'scales', parseGroupScales);
116
123
  if (audit.ladders !== undefined) {
117
124
  next.ladderMinStepPx = parseLadderOptions(audit.ladders);