stylelint-plugin-rhythmguard 3.14.0 → 3.15.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.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,27 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.15.0] - 2026-10-30
10
+
11
+ ### Added
12
+
13
+ - `--include-non-authored` (`includeNonAuthored` in `createAuditReport`, `audit.includeNonAuthored` in `.rhythmguardrc.json`) audits vendored and built stylesheets again; see Changed. ([#161](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/161))
14
+
15
+ ### Changed
16
+
17
+ - **`rhythmguard audit` reports change by default: it no longer audits vendored, test and built stylesheets.** A vendored Cropper.js or jQuery UI theme, a `font-awesome/` copy or a compiled bundle was audited as authored CSS and often led the report. A stylesheet is now left out when a path segment relative to the audited directory is `vendor`, `vendors`, `third-party` (`third_party`, `thirdparty`), `jquery-ui`, `font-awesome`, `fontawesome`, `generated`, `test`, `tests`, `__tests__`, `spec`, `specs`, `fixture`, `fixtures`, `__fixtures__`, `__snapshots__`, `e2e`, `storybook-static` or `.storybook`; when it is a `*.min.css`; or when its code, comments aside, is one line over 5 KB (a built bundle, caught even when the audited directory is `dist` itself). `lib` and `libs` stay audited, since projects keep their own code there. Skipped files add no findings, are not counted in `scanned.cssFiles` or scale cleanliness, and a baseline finding in one is neither resolved nor new, so `--since-baseline` does not count them as fixed. The report counts them in `scanned.nonAuthoredSkipped` and lists them, each with a reason (`path`, `minified` or `bundle`), in `scanned.nonAuthoredFiles`; the text and Markdown summaries and the quickstart print the count. Scale inference and token chains use the same definition, so tokens declared under `generated/`, `e2e/`, `.storybook/`, `jquery-ui/` or `font-awesome/`, in a `*.min.css` or in a bundle no longer shape a `--scale auto` scale, and the path is now judged relative to the audited directory rather than the working directory. The Stylelint and ESLint rules and `rhythmguard fix` are unchanged. In the quiet benchmark 58 findings leave 8 of the 57 repositories, every one from a test, vendor, fixture, Storybook or font-awesome stylesheet: all 53 `noise:non-authored`, PatternFly's 4 `noise:vendored` (its font-awesome copy) and 1 Salesforce Lightning `drift` in `__fixtures__/`, which the benchmark's own path rule missed. No authored finding moves and no inferred scale changes; see `docs/QUIET_BENCHMARK.md`. ([#161](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/161))
18
+ - `rhythmguard fix` skips the vendored, test, minified and built stylesheets the audit skips, so a decision from `--plan` never rewrites a file the plan did not show; `--include-non-authored` and `audit.includeNonAuthored` rewrite them as before. ([#331](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/331))
19
+ - `tailwind-class-use-scale` exempts hairlines by default, as `use-scale` does. A non-zero length that resolves to one CSS pixel or less (`translate-y-[0.5px]`, `-mt-[1px]`, `m-[-1px]`, `p-[0.0625rem]`) is not reported, so the `0.5px` that is quiet in CSS is quiet in a class string too. The definition is the one the Stylelint rules use: by resolved size through `baseFontSize`, `0` and unitless values never reported, and the exemption applies before `allowNegative`. Set the new `allowHairlines: false` to report them as before. `rhythmguard audit` applies the same default to the class strings it scans, and `RhythmguardTailwindClassOptions` types the rule's options. The motion rule is unchanged, and so are messages and fixes. Only class strings with hairlines report less. ([#159](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/159))
20
+ - Tested on Node 24 and 26 (with Stylelint 17) in addition to Node 20 and 22, and the ESLint companion rules on ESLint 9 as well as 10. A weekly job runs the full suite against Stylelint `next`; 18.0.0-next.0 passes. Peer ranges are unchanged.
21
+ - A release run now fails unless all three packages (`stylelint-plugin-rhythmguard`, `rhythmguard`, `eslint-plugin-rhythmguard`) are on npm at the release version.
22
+ - Feature freeze until 4.0, recorded in `CONTRIBUTING.md` and `ROADMAP.md`; the 2026-10-18 council report is in `docs/COUNCIL_2027-2028.md`. Contributors get `npm run check`, an `.nvmrc`, a dev container for Codespaces, and Discussions for questions.
23
+ - Ionic Framework is no longer in the quiet benchmark or the State of Spacing 2026-09 edition, at the maintainers' request (ionic-team/ionic-framework#31430). The edition now covers 57 repositories: 7972 off-scale values in 8362 CSS files.
24
+
25
+ ### Messages
26
+
27
+ - `rhythmguard fix` prints `N non-authored files left alone (vendored, minified or built CSS; --include-non-authored rewrites them)` when it skipped any.
28
+ - New audit summary line in text output, `Non-authored skipped N (vendored, minified or built CSS; --include-non-authored audits them)`, and Markdown row, `| Non-authored stylesheets skipped (vendored, minified or built; --include-non-authored audits them) | N |`, shown when any stylesheet was skipped. The quickstart's `Skipped` line adds `N vendored, minified or built` to its reasons.
29
+
9
30
  ## [3.14.0] - 2026-10-19
10
31
 
11
32
  ### Added
package/CONTRIBUTING.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  Thank you for being here. Rhythmguard is a small, opinionated tool with one job: keep spacing on a scale. Most of the useful work on it is small too, and a first contribution can land in an afternoon. This page tells you where the useful work is, how the checks run, and what to expect from review.
4
4
 
5
+ ## Your first contribution
6
+
7
+ 1. Pick an issue labelled [`good first issue`](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/good%20first%20issue) and say in a comment that you are taking it, so nobody duplicates the work. Each one names the files to touch and how to know you are done.
8
+ 2. Open the repository in a [Codespace](https://codespaces.new/PetriLahdelma/stylelint-plugin-rhythmguard) (dependencies install themselves), or clone it locally as in [Getting set up](#getting-set-up).
9
+ 3. Write the failing test, make the change, run `npm run check`.
10
+ 4. Open a pull request. CI runs on it, and the maintainer replies within a week.
11
+
12
+ Questions, ideas and "is this a bug?" belong in [Discussions](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/discussions); issues are for work with a clear "done when".
13
+
5
14
  ## Ways to contribute
6
15
 
7
16
  **Report a false positive.** A finding your team considers wrong is the most valuable report we get. It is how percentages and hairlines stopped being findings. Open a [false-positive report](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/new?template=false-positive.yml) with the CSS or class string and your config. No fix required.
@@ -29,7 +38,7 @@ npm ci
29
38
  npm test
30
39
  ```
31
40
 
32
- Node 20.19 or newer. 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 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:
33
42
 
34
43
  | Folder | Proves | Run one |
35
44
  | --- | --- | --- |
@@ -45,12 +54,12 @@ Put a new test where its subject lives. If it needs the real linter, it is a rul
45
54
 
46
55
  ## The local gate
47
56
 
48
- Run these before you push. They are what CI runs, so a green local run means a green PR.
57
+ Run these before you push. They are what CI runs, so a green local run means a green PR. `npm run check` runs all three in order.
49
58
 
50
59
  ```bash
51
60
  npm run lint # eslint
52
61
  npm run typecheck # the published TypeScript declarations against a consumer file and the examples
53
- npm test # 300+ tests, on the Stylelint in the lockfile (17)
62
+ npm test # 600+ tests, on the Stylelint in the lockfile (17)
54
63
  ```
55
64
 
56
65
  Optional, depending on what you touched:
@@ -65,7 +74,7 @@ npm run build:playground # after changing anything under src/ the rules us
65
74
  npm run bench:agents -- --dry-run --limit 4 # the agent eval pipeline, no API key needed
66
75
  ```
67
76
 
68
- The local gate runs on whatever Node you have installed; CI runs Node 20 and 22. 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 20 and 22 against Stylelint 16.0.0, 16 and 17, Node 24 and 26 against Stylelint 17, the ESLint companion rules on ESLint 9, and once a week the full suite against Stylelint `next`. 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.
69
78
 
70
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`.
71
80
 
@@ -73,6 +82,17 @@ If your shell's npm registry is overridden by a corporate `.npmrc`, add `--regis
73
82
 
74
83
  CI for this repository runs on self-hosted runners for pushes and same-repo branches. For pull requests from forks a separate job runs on GitHub-hosted runners with Node 22 and the Stylelint in the lockfile (17), covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
75
84
 
85
+ ## What is frozen until 4.0
86
+
87
+ Rhythmguard is in a feature freeze until 4.0, which ships the week Stylelint 18.0.0 is released (plan: [`docs/COUNCIL_2027-2028.md`](./docs/COUNCIL_2027-2028.md)). Please do not start work on these without an issue where the maintainer has agreed to an exception:
88
+
89
+ - new rule options, property groups, presets, or default scales;
90
+ - motion features and Tailwind class-name features beyond bug fixes;
91
+ - Less support, an MCP server, or a port to `@eslint/css` (#173, #175, #176 say what would reopen them);
92
+ - any change to message text in a patch release.
93
+
94
+ Always welcome: bug fixes with a failing test, false-positive reports, token-source fixes (Style Dictionary, DTCG, Sass maps, token packages), docs, benchmark rows and drift labels, and compatibility work for new Node, Stylelint and ESLint versions.
95
+
76
96
  ## Where things live
77
97
 
78
98
  [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) is the map: the layers under `src/`, which may depend on which, the primitives a rule is assembled from, and the invariants with the test that enforces each. Read it before a change that adds a module, and run `node --test test/contracts/architecture.test.js` after; it fails when a dependency crosses a layer line.
@@ -101,7 +121,8 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
101
121
 
102
122
  - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
103
123
  - Node `>=20.19.0` until 4.0, which raises it to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
104
- - ESLint `>=8.0.0` for the companion rules; tested on 9.
124
+ - ESLint `>=8.0.0` for the companion rules; tested on 9 and 10.
125
+ - Stylelint 18: the full suite passes on 18.0.0-next.0 and runs weekly against `next`; the peer range widens in the week 18.0.0 ships.
105
126
  - CommonJS and ESM entry points; every export has a declaration under `types/`.
106
127
  - Three runtime dependencies: `known-css-properties`, `postcss` and `postcss-value-parser`. `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers and dev dependencies here. `test/contracts/architecture.test.js` fails if a runtime import is not declared.
107
128
 
package/README.md CHANGED
@@ -7,13 +7,13 @@
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=3140)](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=3150)](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
 
14
14
  Rhythmguard is scale-aware rather than a blanket ban: values on your scale pass, values off it are reported with the two nearest steps, and tokens are only ever suggested from a map you control. It works on CSS and SCSS declarations through Stylelint and on Tailwind class strings through an ESLint companion, and it ships an audit CLI so you can measure drift and ratchet it down before enforcing anything.
15
15
 
16
- What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). It reads CSS and SCSS; Less and CSS-in-JS are not read. Pair it with a color linter if you need one; do not expect one tool to do both.
16
+ What it is not: it does not check colors or hex values, and the Stylelint rules do not see Tailwind class strings (that is the separate ESLint companion below). It reads CSS and SCSS; Less and CSS-in-JS are not read. Pair it with a color linter if you need one; do not expect one tool to do both. Nor does it judge type for reading: whether a measure, a fluid heading or a number column works for the reader is the job of [Measured Type](#type-pair-it-with-measured-type).
17
17
 
18
18
  ## Start here
19
19
 
@@ -117,13 +117,34 @@ The audit scans CSS declarations, Tailwind class strings and your token contract
117
117
  - [Product analysis, September 2026](docs/STRATEGY_2026-09.md): the market data behind the roadmap
118
118
  - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/) runs the real rules, bundled for the browser, on CSS or SCSS you paste; `scale: "auto"`, tokens and fixes included, and a test proves it reports what Stylelint reports
119
119
 
120
+ ## Type: pair it with Measured Type
121
+
122
+ Rhythmguard keeps every value on the scale; it does not decide whether the scale reads well. [Measured Type](https://github.com/PetriLahdelma/measured-type), a coding-agent skill by the same author, does that part: Bringhurst's rules applied to CSS, with line length, zoom, contrast, tabular figures and font features measured in a real browser. Let it build the type scale and Rhythmguard hold everyone to it:
123
+
124
+ ```bash
125
+ node scripts/type-scale.js --base 1rem:1.125rem --ratio 1.2:1.25 --steps 5 --fluid-from 4 --prefix font-size
126
+ ```
127
+
128
+ That writes `--font-size-*` tokens, which the `typography` group reads with `"auto"`. Add your label and caption sizes to the same file, then list it next to your spacing tokens:
129
+
130
+ ```json
131
+ "rhythmguard/use-scale": [true, {
132
+ "propertyGroups": ["spacing", "typography"],
133
+ "scale": "auto",
134
+ "scaleSources": ["src/space.css", "src/type.css"],
135
+ "scales": { "typography": "auto" }
136
+ }]
137
+ ```
138
+
139
+ The two do not overlap. Rhythmguard reports the `13px` padding and the `17px` heading nobody chose; Measured Type reports the `3vw` size that cannot grow with zoom (Rhythmguard skips viewport units by design) and the `66ch` measure that sets 81 characters per line in Verdana. The worked example, run with Stylelint 17.16 and Rhythmguard 3.14.0, is in [Measured Type's README](https://github.com/PetriLahdelma/measured-type#pairs-with-rhythmguard).
140
+
120
141
  ## Compatibility
121
142
 
122
- Stylelint 16 and 17. 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)). The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9, and has been checked by hand on ESLint 10 and Oxlint 1.85. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x. Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
143
+ Stylelint 16 and 17. 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)). The ESLint companion needs ESLint 8 or newer, is tested on ESLint 9 and 10, and has been checked by hand on Oxlint 1.85. Three runtime dependencies (`known-css-properties`, `postcss`, `postcss-value-parser`); `postcss-scss`, `stylelint-config-tailwindcss` and `stylelint-plugin-logical-css` are optional peers. CommonJS and ESM entry points, TypeScript declarations for every export. The CI matrix runs Node 20 and 22 against Stylelint 16.0.0, 16.x and 17.x, and Node 24 and 26 against 17.x; a weekly job runs the suite against Stylelint `next` (18.0.0-next.0 passes). Upgrading from 2.x: [docs/MIGRATING_TO_3.md](docs/MIGRATING_TO_3.md).
123
144
 
124
145
  ## Contributing and support
125
146
 
126
- Development setup, semver policy, benchmarking and the release process are in [CONTRIBUTING.md](CONTRIBUTING.md). Bugs and feature requests: [GitHub issues](https://github.com/petrilahdelma/stylelint-plugin-rhythmguard/issues). Security: see [SECURITY.md](SECURITY.md).
147
+ Questions and ideas: [Discussions](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/discussions). Bugs and false positives: [GitHub issues](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues). Want to help? Issues labelled [good first issue](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/labels/good%20first%20issue) name the files to touch and how to know you are done, and [CONTRIBUTING.md](CONTRIBUTING.md) gets you from clone (or a [Codespace](https://codespaces.new/PetriLahdelma/stylelint-plugin-rhythmguard)) to a passing `npm run check`. Development setup, semver policy, the feature freeze until 4.0 and the release process are there too. Security: see [SECURITY.md](SECURITY.md).
127
148
 
128
149
  ## License
129
150
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stylelint-plugin-rhythmguard",
3
- "version": "3.14.0",
3
+ "version": "3.15.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"
@@ -132,6 +132,7 @@
132
132
  "bench:perf": "node scripts/bench/compare.mjs",
133
133
  "bench:perf:fix": "node scripts/bench/compare.mjs --fix",
134
134
  "bench:quiet": "node scripts/bench/quiet.mjs",
135
+ "check": "npm run lint && npm run typecheck && npm test",
135
136
  "lint": "eslint .",
136
137
  "scales:add": "node scripts/scales/add-scale.mjs",
137
138
  "scales:validate": "node scripts/scales/validate-community-scales.mjs",
@@ -180,7 +181,7 @@
180
181
  "postcss-value-parser": "^4.2.0"
181
182
  },
182
183
  "devDependencies": {
183
- "@anthropic-ai/sdk": "^0.133.0",
184
+ "@anthropic-ai/sdk": "^0.137.0",
184
185
  "@eslint/js": "^10.0.0",
185
186
  "@types/node": "^22.20.1",
186
187
  "c8": "^12.0.0",
package/src/audit/args.js CHANGED
@@ -59,6 +59,8 @@ const OPTIONS = [
59
59
  apply: (p) => { p.checkMathBounds = true; setFrom(p, 'checkMathBounds'); } },
60
60
  { flag: '--include-motion', kind: 'flag', help: 'Include opt-in motion duration/easing drift',
61
61
  apply: (p) => { p.includeMotion = true; setFrom(p, 'includeMotion'); } },
62
+ { 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)'],
63
+ apply: (p) => { p.includeNonAuthored = true; setFrom(p, 'includeNonAuthored'); } },
62
64
  { flag: '--token-source', kind: 'value', value: '<file>', help: 'External token source (repeatable, comma-separated)',
63
65
  apply: (p, raw) => { p.tokenSources.push(...parseTokenSourcePaths(raw)); setFrom(p, 'tokenSources'); } },
64
66
  { flag: '--token-source-format', kind: 'value', value: '<format>', help: 'Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)',
@@ -8,8 +8,9 @@ const { PROPERTY_GROUP_PATTERNS } = require('../core/css-vocabulary');
8
8
  const { numbersEqual, parseLengthToken, toPx } = require('../core/length');
9
9
  const { negateReplacement } = require('../core/token-index');
10
10
  const { isTokenFunction, propertyMatches, walkRootValueNodes } = require('../core/value-nodes');
11
+ const { nonAuthoredReason } = require('./non-authored');
11
12
  const { formatPath } = require('./shared');
12
- const { isCssFile, isPathInside, isScssFile, isTemplateFile, walkFiles } = require('./scan/files');
13
+ const { isCssFile, isPathInside, isScssFile, isTemplateFile, toPosixRelativePath, walkFiles } = require('./scan/files');
13
14
  const { resolveScssSyntax } = require('./scan/stylesheets');
14
15
 
15
16
  /**
@@ -134,7 +135,7 @@ function parseStylesheet(filePath, source) {
134
135
  * as the audit takes them; the audit's generated and vendored directories
135
136
  * (node_modules, dist, build and the rest of SKIP_DIRS) are always skipped.
136
137
  */
137
- function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties = null, px, replacement, replacements, write = false }) {
138
+ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], includeNonAuthored = false, properties = null, px, replacement, replacements, write = false }) {
138
139
  const rootDir = path.resolve(process.cwd(), dir);
139
140
  const walked = walkFiles(rootDir, ignorePatterns);
140
141
  const files = walked.cssFiles.filter(isCssFile).sort();
@@ -144,7 +145,14 @@ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties =
144
145
  .map((link) => ({ file: formatPath(path.join(rootDir, link)), reason: 'symbolic link to a path outside the directory; not followed' }));
145
146
  const realRoot = fs.realpathSync(rootDir);
146
147
  const rewritten = new Set();
148
+ let nonAuthoredSkipped = 0;
147
149
  for (const filePath of files) {
150
+ // The audit's non-authored check, judged relative to the same root, so a
151
+ // decision from --plan never rewrites a file the plan did not show (#331).
152
+ if (!includeNonAuthored && nonAuthoredReason(toPosixRelativePath(rootDir, filePath), () => fs.readFileSync(filePath, 'utf8'))) {
153
+ nonAuthoredSkipped += 1;
154
+ continue;
155
+ }
148
156
  // Never write through a symbolic link: a file is rewritten only at its own
149
157
  // path inside the directory, and only once (#289).
150
158
  const realPath = writableRealPath(filePath, rootDir, realRoot);
@@ -178,7 +186,7 @@ function runCodemod({ baseFontSize = 16, dir, ignorePatterns = [], properties =
178
186
  }
179
187
  results.push({ changes, file: formatPath(filePath) });
180
188
  }
181
- return { results, skipped };
189
+ return { nonAuthoredSkipped, results, skipped };
182
190
  }
183
191
 
184
192
  /**
@@ -110,6 +110,7 @@ function applyAuditConfig(parsed, configResult) {
110
110
  applyConfigScalar(next, audit, cliOptions, 'tokenKind', 'tokenKind', normalizeTokenKind);
111
111
  applyConfigScalar(next, audit, cliOptions, 'baseFontSize', 'baseFontSize', parseBaseFontSize);
112
112
  applyConfigScalar(next, audit, cliOptions, 'includeMotion', 'includeMotion', parseBooleanOption);
113
+ applyConfigScalar(next, audit, cliOptions, 'includeNonAuthored', 'includeNonAuthored', parseBooleanOption);
113
114
  applyConfigScalar(next, audit, cliOptions, 'checkMathBounds', 'checkMathBounds', parseBooleanOption);
114
115
  applyConfigScalar(next, audit, cliOptions, 'scales', 'scales', parseGroupScales);
115
116
  if (audit.ladders !== undefined) {
@@ -234,6 +234,7 @@ function buildReport({
234
234
  includeMotion,
235
235
  linksOutsideRoot = [],
236
236
  motionFindings,
237
+ nonAuthoredFiles = [],
237
238
  parseErrorFindings = [],
238
239
  readSource,
239
240
  scale,
@@ -322,6 +323,9 @@ function buildReport({
322
323
  scssFiles,
323
324
  scssSkipped,
324
325
  stylelintIgnored,
326
+ // Vendored, minified or built stylesheets left out of the audit (#161).
327
+ nonAuthoredSkipped: nonAuthoredFiles.length,
328
+ nonAuthoredFiles,
325
329
  templateFiles: templateFiles.length,
326
330
  totalFiles,
327
331
  // Symbolic links that resolve outside the scanned directory: not followed (#289).
@@ -466,7 +470,30 @@ const AUDIT_JSON_SCHEMA = Object.freeze({
466
470
  },
467
471
  type: 'object',
468
472
  },
469
- scanned: { type: 'object' },
473
+ scanned: {
474
+ additionalProperties: true,
475
+ properties: {
476
+ nonAuthoredFiles: {
477
+ description: 'Stylesheets not audited because they look vendored, generated, test-only, minified or built. Empty with --include-non-authored.',
478
+ items: {
479
+ additionalProperties: false,
480
+ properties: {
481
+ file: { type: 'string' },
482
+ reason: { enum: ['path', 'minified', 'bundle'] },
483
+ },
484
+ required: ['file', 'reason'],
485
+ type: 'object',
486
+ },
487
+ type: 'array',
488
+ },
489
+ nonAuthoredSkipped: {
490
+ description: 'Number of stylesheets in nonAuthoredFiles.',
491
+ minimum: 0,
492
+ type: 'integer',
493
+ },
494
+ },
495
+ type: 'object',
496
+ },
470
497
  schemaVersion: { const: '2.0' },
471
498
  summary: {
472
499
  additionalProperties: true,
@@ -0,0 +1,77 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * What the audit counts as non-authored CSS (#161): vendored, test, generated
5
+ * and built stylesheets. One definition for every part of the audit: scale
6
+ * inference and token chains never read these files, and the findings side
7
+ * skips them unless `--include-non-authored` is passed. The quiet benchmark's
8
+ * `noise:non-authored` path rule covers the same segments.
9
+ */
10
+
11
+ /**
12
+ * A path segment that marks a directory as not written by the project: tests
13
+ * and fixtures, vendored and third-party code, generated output and Storybook
14
+ * builds. Matched against the root-relative path, whole segments only, so
15
+ * `src/vendorize.css` stays authored. `lib` and `libs` are not on the list:
16
+ * Discourse's `stylesheets/lib/`, SvelteKit's `src/lib/` and Nx's `libs/`
17
+ * hold the project's own code.
18
+ */
19
+ const NON_AUTHORED_SEGMENT = /(^|\/)(test|tests|__tests__|spec|specs|fixtures?|__fixtures__|__snapshots__|e2e|vendors?|third[-_]?party|jquery-ui|font-?awesome|generated|node_modules|dist|build|storybook-static|\.storybook)(\/|$)/i;
20
+
21
+ const MINIFIED_FILE = /\.min\.css$/i;
22
+
23
+ /**
24
+ * A built bundle: its code, comments aside, is one line longer than this many
25
+ * bytes. 5 KB is well past any hand-written one-line stylesheet (a reset or a
26
+ * single component) and well under a framework or app bundle, which run from
27
+ * tens of KB up. A license banner or a trailing source map comment on lines of
28
+ * their own does not make a bundle multi-line.
29
+ */
30
+ const BUNDLE_MIN_BYTES = 5 * 1024;
31
+
32
+ const COMMENT = /\/\*[\s\S]*?\*\//g;
33
+
34
+ function isNonAuthoredPath(relativePath) {
35
+ const file = String(relativePath).replace(/\\/g, '/');
36
+ return NON_AUTHORED_SEGMENT.test(file) || MINIFIED_FILE.test(file);
37
+ }
38
+
39
+ function isBuiltBundle(source) {
40
+ const text = String(source);
41
+ if (Buffer.byteLength(text, 'utf8') <= BUNDLE_MIN_BYTES) {
42
+ return false;
43
+ }
44
+ const code = (text.includes('/*') ? text.replace(COMMENT, '') : text).trim();
45
+ return !code.includes('\n') && Buffer.byteLength(code, 'utf8') > BUNDLE_MIN_BYTES;
46
+ }
47
+
48
+ /**
49
+ * Why a stylesheet is not authored, or null when it is: `path` for a
50
+ * non-authored directory, `minified` for `*.min.css`, `bundle` for a one-line
51
+ * stylesheet over 5 KB. The file is read only when its path does not decide;
52
+ * one that cannot be read is left to the audit, which reports it.
53
+ */
54
+ function nonAuthoredReason(relativePath, readSource) {
55
+ const file = String(relativePath).replace(/\\/g, '/');
56
+ if (NON_AUTHORED_SEGMENT.test(file)) {
57
+ return 'path';
58
+ }
59
+ if (MINIFIED_FILE.test(file)) {
60
+ return 'minified';
61
+ }
62
+ let source;
63
+ try {
64
+ source = readSource();
65
+ } catch {
66
+ return null;
67
+ }
68
+ return isBuiltBundle(source) ? 'bundle' : null;
69
+ }
70
+
71
+ module.exports = {
72
+ BUNDLE_MIN_BYTES,
73
+ NON_AUTHORED_SEGMENT,
74
+ isBuiltBundle,
75
+ isNonAuthoredPath,
76
+ nonAuthoredReason,
77
+ };
@@ -28,6 +28,7 @@ function renderMarkdown(report) {
28
28
  ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
29
29
  ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
30
30
  ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
31
+ ...(report.scanned && report.scanned.nonAuthoredSkipped > 0 ? [`| Non-authored stylesheets skipped (vendored, minified or built; --include-non-authored audits them) | ${report.scanned.nonAuthoredSkipped} |`] : []),
31
32
  ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [`| Symbolic links not followed (they point outside the scanned directory) | ${report.scanned.linksOutsideRoot} |`] : []),
32
33
  ...(parseErrors(report).length > 0 ? [`| Stylesheets that failed to parse (not audited) | ${parseErrors(report).length} |`] : []),
33
34
  `| Files with issues | ${report.filesWithIssues} |`,
@@ -22,6 +22,7 @@ function renderText(report) {
22
22
  ...(report.scanned && report.scanned.scssFiles > 0 ? [` SCSS files scanned ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
23
23
  ...(report.scanned && report.scanned.scssSkipped > 0 ? [` SCSS files skipped ${String(report.scanned.scssSkipped).padStart(4)} (install postcss-scss to audit them)`] : []),
24
24
  ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [` Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)} (not audited)`] : []),
25
+ ...(report.scanned && report.scanned.nonAuthoredSkipped > 0 ? [` Non-authored skipped ${String(report.scanned.nonAuthoredSkipped).padStart(4)} (vendored, minified or built CSS; --include-non-authored audits them)`] : []),
25
26
  ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [` Links not followed ${String(report.scanned.linksOutsideRoot).padStart(4)} (they point outside the scanned directory)`] : []),
26
27
  ...(parseErrors(report).length > 0 ? [` Parse errors ${String(parseErrors(report).length).padStart(4)} (not audited)`] : []),
27
28
  ` Files with issues ${String(report.filesWithIssues).padStart(4)}`,
@@ -28,7 +28,8 @@ const { buildGroupScales } = require('../core/options');
28
28
  const { applyDecisions, buildDecisionPlan } = require('./decisions');
29
29
  const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
30
30
  const { resolveTokenLadders, toLaddersContract } = require('./token-ladders');
31
- const { assertDirectory, getScanFiles, readSourceFromDisk } = require('./scan/files');
31
+ const { assertDirectory, getScanFiles, readSourceFromDisk, toPosixRelativePath } = require('./scan/files');
32
+ const { nonAuthoredReason } = require('./non-authored');
32
33
  const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
33
34
  const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
34
35
 
@@ -39,10 +40,21 @@ async function createAuditReport(options) {
39
40
 
40
41
  const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
41
42
 
42
- const { cssFiles, scanScope, templateFiles } = scanFiles;
43
+ const { scanScope, templateFiles } = scanFiles;
43
44
  // A --staged run reads each changed file as the index holds it.
44
45
  const readSource = scanFiles.readSource || readSourceFromDisk;
45
46
 
47
+ // Vendored, test, generated and built stylesheets (#161). They never shape
48
+ // the scale or the token chains; unless --include-non-authored, they are
49
+ // not audited either, like a file in a skipped directory.
50
+ const nonAuthored = classifyNonAuthored(scanFiles.cssFiles, resolvedDir, readSource);
51
+ const nonAuthoredSkipped = parsed.includeNonAuthored
52
+ ? []
53
+ : scanFiles.cssFiles.filter((file) => nonAuthored.has(file));
54
+ const cssFiles = parsed.includeNonAuthored
55
+ ? scanFiles.cssFiles
56
+ : scanFiles.cssFiles.filter((file) => !nonAuthored.has(file));
57
+
46
58
  // A configured source that gives nothing is a warning, not a silent fallback (issue #163).
47
59
  const tokenSourceResult = parseTokenSources({
48
60
  baseFontSize: parsed.baseFontSize,
@@ -63,6 +75,7 @@ async function createAuditReport(options) {
63
75
  const scale = resolveAuditScale({
64
76
  baseFontSize: parsed.baseFontSize,
65
77
  cssFiles,
78
+ isNonAuthored: (file) => nonAuthored.has(file),
66
79
  readSource,
67
80
  requested: spacingOverride || parsed.scale,
68
81
  tokenSourceResult: spacingSourceResult,
@@ -105,6 +118,7 @@ async function createAuditReport(options) {
105
118
  includeMotion: parsed.includeMotion,
106
119
  linksOutsideRoot: scanFiles.linksOutsideRoot || [],
107
120
  motionFindings,
121
+ nonAuthoredFiles: nonAuthoredSkipped.map((file) => ({ file: formatPath(file), reason: nonAuthored.get(file) })),
108
122
  parseErrorFindings,
109
123
  readSource,
110
124
  scale,
@@ -124,7 +138,7 @@ async function createAuditReport(options) {
124
138
  cssFiles,
125
139
  externalDefinitions: tokenSourceResult.definitions,
126
140
  readSource,
127
- skipFile: (file) => NON_AUTHORED_SEGMENT.test(file),
141
+ skipFile: (file) => nonAuthored.has(path.resolve(file)),
128
142
  });
129
143
  report.tokenContract.chains = toChainsContract(resolveTokenChains({
130
144
  baseFontSize: parsed.baseFontSize,
@@ -152,6 +166,8 @@ async function createAuditReport(options) {
152
166
  if (parsed.sinceBaseline || parsed.writeBaseline) {
153
167
  const unauditedFiles = [
154
168
  ...(cssResults.unauditedFiles || []),
169
+ // A skipped non-authored stylesheet was not audited: its baseline findings are neither resolved nor new.
170
+ ...nonAuthoredSkipped,
155
171
  ...parseErrorFindings.map((finding) => path.resolve(process.cwd(), finding.file)),
156
172
  ];
157
173
  const unaudited = new Set(unauditedFiles);
@@ -190,14 +206,30 @@ function chainDefinitions(parsed) {
190
206
  }).definitions;
191
207
  }
192
208
 
193
- const NON_AUTHORED_SEGMENT = /(^|\/)(test|tests|__tests__|spec|specs|fixtures?|__fixtures__|__snapshots__|vendor|third[-_]?party|storybook-static)(\/|$)/i;
209
+ /**
210
+ * The non-authored stylesheets among `cssFiles` (absolute paths), each with
211
+ * its reason (`path`, `minified` or `bundle`), judged by the path relative to
212
+ * the audited directory: auditing `dist` itself still skips the built bundles
213
+ * in it, by name or by shape, and a project checked out under a `vendor`
214
+ * directory is not skipped as a whole.
215
+ */
216
+ function classifyNonAuthored(cssFiles, rootDir, readSource) {
217
+ const classified = new Map();
218
+ for (const file of cssFiles) {
219
+ const reason = nonAuthoredReason(toPosixRelativePath(rootDir, file), () => readSource(file));
220
+ if (reason) {
221
+ classified.set(file, reason);
222
+ }
223
+ }
224
+ return classified;
225
+ }
194
226
 
195
227
  /**
196
228
  * One project-level scale for the whole audit, with provenance.
197
229
  * "auto": external token sources, then spacing custom properties across the scanned
198
230
  * CSS, then the default scale. First source that yields values wins.
199
231
  */
200
- function resolveAuditScale({ baseFontSize, cssFiles, readSource = readSourceFromDisk, requested, tokenSourceResult }) {
232
+ function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false, readSource = readSourceFromDisk, requested, tokenSourceResult }) {
201
233
  if (Array.isArray(requested)) {
202
234
  return {
203
235
  files: [],
@@ -224,8 +256,8 @@ function resolveAuditScale({ baseFontSize, cssFiles, readSource = readSourceFrom
224
256
  const matchesKind = createTokenKindMatcher('spacing');
225
257
  for (const filePath of cssFiles) {
226
258
  // Test, fixture and vendored stylesheets often redefine tokens to exercise
227
- // overrides; they are findings noise and must not shape the inferred scale.
228
- if (NON_AUTHORED_SEGMENT.test(formatPath(filePath))) {
259
+ // overrides; they must not shape the inferred scale, even when audited.
260
+ if (isNonAuthored(filePath)) {
229
261
  continue;
230
262
  }
231
263
  let text;
@@ -77,6 +77,7 @@ function createDefaultAuditOptions() {
77
77
  ignorePatterns: [],
78
78
  checkMathBounds: false,
79
79
  includeMotion: false,
80
+ includeNonAuthored: false,
80
81
  ladderMinStepPx: 2,
81
82
  maxFindings: null,
82
83
  minCleanliness: null,
package/src/cli/fix.js CHANGED
@@ -9,8 +9,10 @@ const { normalizeCreateAuditOptions } = require('../audit/report');
9
9
  const { assertDirectory } = require('../audit/scan/files');
10
10
  const { DEFAULT_IGNORE_PATH } = require('../audit/shared');
11
11
 
12
- // --ignore and --ignore-path are the audit's own flags, parsed by the audit's table.
13
- const IGNORE_OPTIONS = AUDIT_OPTIONS.filter((option) => option.flag === '--ignore' || option.flag === '--ignore-path');
12
+ // --ignore, --ignore-path and --include-non-authored are the audit's own flags,
13
+ // parsed by the audit's table, so fix skips exactly what the audit skips (#331).
14
+ const SHARED_FLAGS = new Set(['--ignore', '--ignore-path', '--include-non-authored']);
15
+ const IGNORE_OPTIONS = AUDIT_OPTIONS.filter((option) => SHARED_FLAGS.has(option.flag));
14
16
 
15
17
  const HELP = `Usage: rhythmguard fix <dir> --value <length> --to <replacement> [options]
16
18
  rhythmguard fix <dir> --decided [options]
@@ -20,8 +22,8 @@ execute the snap decisions in .rhythmguardrc.json that name a "to". Matching is
20
22
  by px, so --value 10px also rewrites 0.625rem. Token definitions, values inside
21
23
  var()/theme()/token(), and non-spacing properties are never touched. Dry run by
22
24
  default. Files the audit skips are skipped too: .rhythmguardignore, audit.ignore
23
- in .rhythmguardrc.json, --ignore, and generated or vendored directories such as
24
- node_modules and dist.
25
+ in .rhythmguardrc.json, --ignore, generated directories such as node_modules
26
+ and dist, and vendored, test, minified and built stylesheets.
25
27
 
26
28
  Options:
27
29
  --value <length> The literal to replace, for example 10px or 0.625rem
@@ -31,6 +33,7 @@ Options:
31
33
  --base-font-size <px> Base for rem/em conversion (default: 16)
32
34
  --ignore <pattern> Exclude a root-relative path or glob (repeatable, comma-separated)
33
35
  --ignore-path <file> Load ignore patterns from file (default: .rhythmguardignore when present)
36
+ --include-non-authored Rewrite vendored, test, minified and built stylesheets too
34
37
  --write Apply the changes; without it, only list them
35
38
  --help Show this help message
36
39
  `;
@@ -44,6 +47,7 @@ function parseArgs(argv) {
44
47
  help: false,
45
48
  ignorePath: DEFAULT_IGNORE_PATH,
46
49
  ignorePatterns: [],
50
+ includeNonAuthored: false,
47
51
  properties: null,
48
52
  replacement: null,
49
53
  value: null,
@@ -53,7 +57,8 @@ function parseArgs(argv) {
53
57
  const arg = argv[index];
54
58
  const next = () => argv[++index];
55
59
  const ignoreOption = IGNORE_OPTIONS.find((option) => arg === option.flag || arg.startsWith(`${option.flag}=`));
56
- if (ignoreOption) ignoreOption.apply(parsed, arg === ignoreOption.flag ? next() : arg.slice(ignoreOption.flag.length + 1));
60
+ if (ignoreOption && ignoreOption.kind === 'flag' && arg === ignoreOption.flag) ignoreOption.apply(parsed);
61
+ else if (ignoreOption && ignoreOption.kind !== 'flag') ignoreOption.apply(parsed, arg === ignoreOption.flag ? next() : arg.slice(ignoreOption.flag.length + 1));
57
62
  else if (arg === '--help' || arg === '-h') parsed.help = true;
58
63
  else if (arg === '--write') parsed.write = true;
59
64
  else if (arg === '--decided') parsed.decided = true;
@@ -85,16 +90,19 @@ function lengthToPx(value, baseFontSize) {
85
90
  }
86
91
 
87
92
  /**
88
- * The ignore list, loaded exactly as the audit loads it: .rhythmguardrc.json's
89
- * audit.ignore and audit.ignorePath, the ignore file, then --ignore.
93
+ * What to skip, loaded exactly as the audit loads it: .rhythmguardrc.json's
94
+ * audit.ignore, audit.ignorePath and audit.includeNonAuthored, the ignore file,
95
+ * then --ignore and --include-non-authored.
90
96
  */
91
- function auditIgnorePatterns(parsed) {
92
- return resolveIgnorePatterns(normalizeCreateAuditOptions({
97
+ function auditSkipOptions(parsed) {
98
+ const options = normalizeCreateAuditOptions({
93
99
  cliOptions: parsed.cliOptions,
94
100
  dir: parsed.dir,
95
101
  ignorePath: parsed.ignorePath,
96
102
  ignorePatterns: parsed.ignorePatterns,
97
- }));
103
+ includeNonAuthored: parsed.includeNonAuthored,
104
+ });
105
+ return { ignorePatterns: resolveIgnorePatterns(options), includeNonAuthored: options.includeNonAuthored === true };
98
106
  }
99
107
 
100
108
  /** The replacements to run: one from --value/--to, or every snap decision with a "to". */
@@ -134,13 +142,13 @@ function run() {
134
142
  }
135
143
 
136
144
  let plan;
137
- let ignorePatterns;
145
+ let skipOptions;
138
146
  try {
139
147
  // The same check, and the same message, as the audit: a missing path or a
140
148
  // file reads "Directory not found" or "Not a directory", not a stack trace (#288).
141
149
  assertDirectory(parsed.dir);
142
150
  plan = plannedReplacements(parsed);
143
- ignorePatterns = auditIgnorePatterns(parsed);
151
+ skipOptions = auditSkipOptions(parsed);
144
152
  } catch (error) {
145
153
  process.stderr.write(`${error.message}\n`);
146
154
  process.exit(1);
@@ -152,11 +160,12 @@ function run() {
152
160
  // Every replacement in one pass over the original values: a value one snap
153
161
  // writes is never snapped again, and the dry run lists exactly what --write writes.
154
162
  const outcome = plan.replacements.length === 0
155
- ? { results: [], skipped: [] }
163
+ ? { nonAuthoredSkipped: 0, results: [], skipped: [] }
156
164
  : runCodemod({
157
165
  baseFontSize: parsed.baseFontSize,
158
166
  dir: parsed.dir,
159
- ignorePatterns,
167
+ ignorePatterns: skipOptions.ignorePatterns,
168
+ includeNonAuthored: skipOptions.includeNonAuthored,
160
169
  properties: parsed.properties,
161
170
  replacements: plan.replacements,
162
171
  write: parsed.write,
@@ -180,6 +189,10 @@ function run() {
180
189
  const noun2 = plan.skippedSnaps.length === 1 ? 'snap decision has' : 'snap decisions have';
181
190
  lines.push(`${plan.skippedSnaps.length} ${noun2} no "to" and ${plan.skippedSnaps.length === 1 ? 'was' : 'were'} skipped: ${plan.skippedSnaps.join(', ')}`);
182
191
  }
192
+ if (outcome.nonAuthoredSkipped > 0) {
193
+ const noun3 = outcome.nonAuthoredSkipped === 1 ? 'file' : 'files';
194
+ lines.push(`${outcome.nonAuthoredSkipped} non-authored ${noun3} left alone (vendored, minified or built CSS; --include-non-authored rewrites them)`);
195
+ }
183
196
  for (const entry of skipped) {
184
197
  lines.push(`skipped ${entry.file}: ${entry.reason}`);
185
198
  }
@@ -201,7 +201,7 @@ async function run() {
201
201
  }
202
202
 
203
203
  const scanned = report.scanned || {};
204
- const skippedStylesheets = (scanned.scssSkipped || 0) + (scanned.stylelintIgnored || 0);
204
+ const skippedStylesheets = (scanned.scssSkipped || 0) + (scanned.stylelintIgnored || 0) + (scanned.nonAuthoredSkipped || 0);
205
205
  if (report.cssFilesScanned === 0 && report.templateFilesScanned === 0 && skippedStylesheets === 0) {
206
206
  out.push(' No CSS files found here. Run from your project root, or audit a directory directly:');
207
207
  out.push(' npx rhythmguard audit ./src', '');
@@ -230,6 +230,7 @@ async function run() {
230
230
  const reasons = [
231
231
  ...(scanned.scssSkipped > 0 ? [`${scanned.scssSkipped} SCSS without postcss-scss`] : []),
232
232
  ...(scanned.stylelintIgnored > 0 ? [`${scanned.stylelintIgnored} in .stylelintignore`] : []),
233
+ ...(scanned.nonAuthoredSkipped > 0 ? [`${scanned.nonAuthoredSkipped} vendored, minified or built`] : []),
233
234
  ];
234
235
  out.push(` Skipped ${skippedStylesheets} not audited (${reasons.join(', ')})`);
235
236
  }
@@ -3,6 +3,7 @@
3
3
  const {
4
4
  formatLength,
5
5
  formatNumber,
6
+ isHairlineLength,
6
7
  nearestScaleValues,
7
8
  nearestText,
8
9
  normalizeScale,
@@ -31,6 +32,7 @@ function normalizeTailwindClassOptions(option = {}) {
31
32
  ? option.baseFontSize
32
33
  : 16;
33
34
  return {
35
+ allowHairlines: option.allowHairlines !== false,
34
36
  allowNegative: option.allowNegative !== false,
35
37
  baseFontSize,
36
38
  scale: Array.isArray(option.scale) ? option.scale : DEFAULT_SCALE,
@@ -172,6 +174,12 @@ function analyzeClassToken(token, options, scalePx) {
172
174
  return null;
173
175
  }
174
176
 
177
+ // The same exemption as use-scale, and in the same order: a hairline is not
178
+ // reported, not even as a negative value (#159).
179
+ if (options.allowHairlines && isHairlineLength(parsedLength, options.baseFontSize)) {
180
+ return null;
181
+ }
182
+
175
183
  // `-m-[16px]` and `m-[-16px]` are both negative margins (#241); in
176
184
  // `-m-[-16px]` the two signs cancel and Tailwind writes a positive margin (#277).
177
185
  const negative = match.groups.utility.startsWith('-') !== parsedLength.number < 0;
@@ -44,6 +44,7 @@ module.exports = {
44
44
  {
45
45
  additionalProperties: false,
46
46
  properties: {
47
+ allowHairlines: { type: 'boolean' },
47
48
  allowNegative: { type: 'boolean' },
48
49
  baseFontSize: { type: 'number' },
49
50
  note: { maxLength: MAX_NOTE_LENGTH, minLength: 1, type: 'string' },
@@ -68,12 +68,18 @@ async function runAudit(): Promise<AuditContractReport> {
68
68
  const firstText: string | undefined = report.findings.css[0]?.text;
69
69
  const resolved: number | undefined = report.baseline?.resolvedFindingsCount;
70
70
  const contractConfig: { file: string } | null = toAuditContractReport(report).command.config;
71
+ // Non-authored stylesheets: skipped by default, listed with a reason (#161).
72
+ const withVendored: AuditReport = await createAuditReport({ dir: './src', includeNonAuthored: true });
73
+ const skippedFiles: string[] = (report.scanned.nonAuthoredFiles ?? []).map((entry) => `${entry.file} (${entry.reason})`);
74
+ const skippedCount: number | undefined = withVendored.scanned.nonAuthoredSkipped;
71
75
  void cleanliness;
72
76
  void counts;
73
77
  void configFile;
74
78
  void firstText;
75
79
  void resolved;
76
80
  void contractConfig;
81
+ void skippedFiles;
82
+ void skippedCount;
77
83
  return toAuditContractReport(report);
78
84
  }
79
85
 
@@ -7,6 +7,13 @@ import type { ESLint, Linter } from 'eslint';
7
7
  import { defineConfig } from 'eslint/config';
8
8
  import rhythmguard from 'eslint-plugin-rhythmguard';
9
9
  import companion from 'stylelint-plugin-rhythmguard/eslint';
10
+ import type { RhythmguardTailwindClassOptions } from 'stylelint-plugin-rhythmguard/eslint';
11
+
12
+ const classOptions: RhythmguardTailwindClassOptions = {
13
+ allowHairlines: false,
14
+ scale: [0, 4, 8, 12, 16, 24, 32],
15
+ spacingUnit: false,
16
+ };
10
17
 
11
18
  const config = defineConfig([
12
19
  {
@@ -17,6 +24,11 @@ const config = defineConfig([
17
24
  'rhythmguard-tailwind/tailwind-class-use-scale': ['error', { scale: [0, 4, 8, 12, 16, 24, 32] }],
18
25
  },
19
26
  },
27
+ {
28
+ files: ['**/*.tsx'],
29
+ plugins: { 'rhythmguard-tailwind': rhythmguard },
30
+ rules: { 'rhythmguard-tailwind/tailwind-class-use-scale': ['error', classOptions] },
31
+ },
20
32
  {
21
33
  files: ['**/*.jsx'],
22
34
  plugins: { 'rhythmguard-tailwind': companion },
package/types/audit.d.ts CHANGED
@@ -48,6 +48,11 @@ export interface AuditOptions {
48
48
  /** Check clamp() bounds and min()/max() arguments against the scale (equivalent to `--check-math-bounds`). */
49
49
  checkMathBounds?: boolean;
50
50
  includeMotion?: boolean;
51
+ /**
52
+ * Audit vendored, test, generated, minified and built stylesheets too (equivalent to `--include-non-authored`).
53
+ * Off by default: they are listed in `scanned.nonAuthoredFiles` and not audited.
54
+ */
55
+ includeNonAuthored?: boolean;
51
56
  /** Smallest gap in px between neighbouring steps of a token ladder (`audit.ladders.minStepPx`). Default 2. */
52
57
  ladderMinStepPx?: number;
53
58
  /** A scale per property group (`spacing`, `radius`, `size`, `typography`): values, a preset name or "auto". Each group named is also checked. */
@@ -109,12 +114,23 @@ export interface AuditScanned {
109
114
  scssSkipped?: number;
110
115
  /** Stylesheets Stylelint skipped because the project's own .stylelintignore excludes them. */
111
116
  stylelintIgnored?: number;
117
+ /** Stylesheets not audited because they look vendored, generated, test-only, minified or built. 0 with `includeNonAuthored`. */
118
+ nonAuthoredSkipped?: number;
119
+ /** The stylesheets counted in `nonAuthoredSkipped`, with why each was skipped. */
120
+ nonAuthoredFiles?: AuditNonAuthoredFile[];
112
121
  templateFiles: number;
113
122
  /** Audited stylesheets plus template files. Stylesheets that failed to parse are taken out of this for cleanliness. */
114
123
  totalFiles?: number;
115
124
  [key: string]: unknown;
116
125
  }
117
126
 
127
+ export interface AuditNonAuthoredFile {
128
+ /** Path as findings name files. */
129
+ file: string;
130
+ /** `path`: a vendor, lib, test, fixture or generated directory; `minified`: `*.min.css`; `bundle`: one line of CSS over 5 KB. */
131
+ reason: "bundle" | "minified" | "path";
132
+ }
133
+
118
134
  export interface AuditFinding {
119
135
  column?: number;
120
136
  file: string;
package/types/eslint.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { RhythmguardEslintPlugin } from "./shared";
2
2
 
3
- export type { EslintRuleModule, RhythmguardEslintPlugin } from "./shared";
3
+ export type { EslintRuleModule, RhythmguardEslintPlugin, RhythmguardTailwindClassOptions } from "./shared";
4
4
 
5
5
  export const configs: RhythmguardEslintPlugin["configs"];
6
6
  export const rules: RhythmguardEslintPlugin["rules"];
package/types/index.d.ts CHANGED
@@ -21,6 +21,7 @@ export type {
21
21
  RhythmguardRuleOptions,
22
22
  RhythmguardStylelintConfig,
23
23
  RhythmguardStylelintRules,
24
+ RhythmguardTailwindClassOptions,
24
25
  RhythmguardTransformRuleOptions,
25
26
  RhythmguardUseScaleOptions,
26
27
  ScaleOverride,
@@ -35,6 +36,7 @@ export type {
35
36
  AuditConfigReference,
36
37
  AuditContractReport,
37
38
  AuditFinding,
39
+ AuditNonAuthoredFile,
38
40
  AuditOptions,
39
41
  AuditReport,
40
42
  AuditScale,
package/types/shared.d.ts CHANGED
@@ -211,6 +211,24 @@ export interface EslintRuleModule {
211
211
  create(context: any): EslintRuleVisitor;
212
212
  }
213
213
 
214
+ /** Options for `rhythmguard-tailwind/tailwind-class-use-scale`. */
215
+ export interface RhythmguardTailwindClassOptions {
216
+ /** Exempt non-zero lengths of one CSS pixel or less (`translate-y-[0.5px]`, `-mt-[1px]`, `p-[0.0625rem]`), as `use-scale` does. Default true. */
217
+ allowHairlines?: boolean;
218
+ /** Allow negative values (`-m-[16px]`, `m-[-16px]`). Default true. */
219
+ allowNegative?: boolean;
220
+ /** Base for converting `rem` and `em`. Default 16. */
221
+ baseFontSize?: number;
222
+ /** A sentence of up to 200 characters appended to every finding, after the built-in text. */
223
+ note?: string;
224
+ /** Allowed values. Default `[0, 4, 8, 12, 16, 24, 32]`. */
225
+ scale?: ScaleValue[];
226
+ /** px per Tailwind spacing step, used to write utility classes in messages and fixes. Default a quarter of `baseFontSize`; `false` keeps arbitrary values. */
227
+ spacingUnit?: number | false;
228
+ /** Units checked. Default `["px", "rem", "em"]`. */
229
+ units?: string[];
230
+ }
231
+
214
232
  export interface RhythmguardEslintPlugin {
215
233
  configs: {
216
234
  /** A flat config that registers the plugin itself, so it can stand alone in a config array. */