stylelint-plugin-rhythmguard 3.17.0 → 3.19.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,54 @@ The format follows Keep a Changelog principles and semantic versioning.
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [3.19.0] - 2026-11-09
10
+
11
+ ### Changed
12
+
13
+ - 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.
14
+ - 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.
15
+
16
+ - 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.
17
+ - 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.
18
+
19
+ - `--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.
20
+ - `--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.
21
+
22
+ - 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:
23
+ - 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.
24
+ - A project with SCSS gets `"customSyntax": "postcss-scss"`.
25
+ - 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.
26
+ - The Stylelint glob comes from where the stylesheets are (`styles/**/*.scss`, not `**/*.css`).
27
+ - `init` writes the same syntax and prints the same install line and glob.
28
+ - The `rhythmguard` package depends on `postcss-scss`, so `npx rhythmguard` audits SCSS on first contact instead of skipping it.
29
+ - 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.
30
+ - `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.
31
+
32
+ - `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.
33
+
34
+ - `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.
35
+ - `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`.
36
+ - 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.
37
+
38
+ - 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.
39
+
40
+ ## [3.18.0] - 2026-11-05
41
+
42
+ ### Changed
43
+
44
+ - Stylelint 18 is supported: the peer range is `^16.7.0 || ^17.0.0 || ^18.0.0` in the plugin and in the `rhythmguard` CLI's dependency, so `npm install stylelint@18 stylelint-config-standard@41 stylelint-plugin-rhythmguard` resolves where it failed with ERESOLVE. No code changed; the full suite passes on 18.0.0. On a Node older than Stylelint 18 needs (22.22, 24.15 or 26), npm installs Stylelint 17 for `npx rhythmguard`. The README says how `use-scale` differs from 18's new `value-type-custom-property-required-list` and how to run both. Closes #168.
45
+ - The Stylelint floor is 16.7.0. On 16.0 to 16.6, Stylelint never read a rule's fix callback, so `--fix` kept every warning and changed nothing. A project on one of those versions gets a peer conflict when it upgrades and resolves it with `npm update stylelint` (any 16.x from 16.7 on). The floor suite now checks that a fix applies.
46
+ - CI and the release verify Stylelint 18 on Node 22, 24 and 26; the floor rows run 16.7.0. The pack and registry smoke tests install the plugin next to Stylelint 16.7.0, 17, and 18 with stylelint-config-standard 41 (18 is skipped on a Node it does not support), and the weekly job tests the newest Stylelint instead of the removed `next` tag.
47
+
48
+ ### Added
49
+
50
+ - `scale: "auto"` reads GitLab's spacing scale: Sass scalars named `$<namespace>-spacing-scale-<n>` count as a scale when a namespace holds at least four lengths, as `$gl-spacing-scale-1` to `$gl-spacing-scale-88` do in gitlab-ui. Other namespaced scalars, such as `$dropdown-spacer`, stay excluded. gitlab-ui's benchmark row is measured against that scale: 3 off-scale values, as before, but `-2px` is now on it and a 14px margin is found.
51
+ - `scale: "auto"` reads `@wikimedia/codex-design-tokens` when it is installed: the `--spacing-0` to `--spacing-400` ladder (0 to 64px). The named `--spacing-*` tokens are computed component values and are left out. Codex has no benchmark row, because its components and most of its consumers are written in Less, which the audit does not read (#175).
52
+
53
+ ### Changed
54
+
55
+ - Sass expressions evaluate `px-to-rem(<n>px)` as that length, in token files and in `use-scale` values. A second argument changes the base and is still skipped, as is any other function. A variable defined with it can now produce a finding where it was invisible before.
56
+
9
57
  ## [3.17.0] - 2026-11-04
10
58
 
11
59
  ### Added
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
  | --- | --- | --- |
@@ -47,7 +47,7 @@ Node 20.19 or newer; `.nvmrc` pins 22 for development, so `nvm use` picks it up.
47
47
  | `test/cli/` | a command as a user runs it, in a temp directory | `node --test test/cli/audit-cli.test.js` |
48
48
  | `test/api/` | the programmatic audit API | |
49
49
  | `test/contracts/` | what must stay true for consumers: package exports, CJS/ESM parity, layer rules, rule docs | `node --test test/contracts/architecture.test.js` |
50
- | `test/compat/` | the Stylelint 16.0.0 floor | `npm run test:compat-floor` |
50
+ | `test/compat/` | the Stylelint 16.7.0 floor | `npm run test:compat-floor` |
51
51
  | `test/bench/` | the benchmark and report scripts | |
52
52
 
53
53
  Put a new test where its subject lives. If it needs the real linter, it is a rule test; if it needs a temp directory and `spawnSync`, it is a CLI test; if it asserts something about the repository itself, it is a contract.
@@ -65,7 +65,7 @@ npm test # 600+ tests, on the Stylelint in the lockfile (17)
65
65
  Optional, depending on what you touched:
66
66
 
67
67
  ```bash
68
- npm run test:compat-floor # Stylelint 16.0.0, the oldest supported
68
+ npm run test:compat-floor # Stylelint 16.7.0, the oldest supported
69
69
  npm run test:pack-smoke # pack all three packages and smoke-test each in a temp project
70
70
  npm run scales:validate # community scale JSON
71
71
  npm run bench:quiet -- --check # findings on the benchmark repos must match snapshots
@@ -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.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.
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
 
@@ -84,7 +84,7 @@ CI for this repository runs on self-hosted runners for pushes and same-repo bran
84
84
 
85
85
  ## What is frozen until 4.0
86
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:
87
+ Rhythmguard is in a feature freeze until 4.0 (plan: [`docs/COUNCIL_2027-2028.md`](./docs/COUNCIL_2027-2028.md), with the dates proposed in [`docs/PRODUCT_REVIEW_2026-11.md`](./docs/PRODUCT_REVIEW_2026-11.md)). Stylelint 18 support shipped in 3.18.0 without waiting for it. Please do not start work on these without an issue where the maintainer has agreed to an exception:
88
88
 
89
89
  - new rule options, property groups, presets, or default scales;
90
90
  - motion features and Tailwind class-name features beyond bug fixes;
@@ -119,10 +119,10 @@ Always welcome: bug fixes with a failing test, false-positive reports, token-sou
119
119
 
120
120
  ## Compatibility
121
121
 
122
- - Stylelint `^16.0.0 || ^17.0.0`. The 16.0.0 floor has known autofix differences; CI runs the floor suite against it.
122
+ - Stylelint `^16.7.0 || ^17.0.0 || ^18.0.0`. 16.7.0 is the first version that applies a rule's fix callback; CI runs the floor suite, fixes included, against it.
123
123
  - Node `>=20.19.0` until 4.0, which raises it to 22.22 ([#172](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/172)).
124
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.
125
+ - Stylelint 18 needs Node ^22.22.2, ^24.15.0 or >=26; CI runs it on Node 22, 24 and 26, and `test/contracts/stylelint-18-pairing.test.js` runs the README's pairing with its new core rule there.
126
126
  - CommonJS and ESM entry points; every export has a declaration under `types/`.
127
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.
128
128
 
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=3170)](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=3190)](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
 
@@ -144,7 +144,21 @@ The two do not overlap. Rhythmguard reports the `13px` padding and the `17px` he
144
144
 
145
145
  ## Compatibility
146
146
 
147
- 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 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. 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).
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
+
149
+ ### Stylelint 18's custom-property rule
150
+
151
+ Stylelint 18 added `value-type-custom-property-required-list`. It answers a different question from `use-scale`. The core rule says a length must be a custom property: it reports `16px` and a `1px` hairline the same way as `13px`, names no step, and `--fix` leaves the value alone. `use-scale` says which value is off your scale and which two steps are nearest, and `--fix` writes the nearest step; `prefer-token` names the token that holds the value; both read the scale from your token file. To move every length to a token over time, run both:
152
+
153
+ ```json
154
+ {
155
+ "plugins": ["stylelint-plugin-rhythmguard"],
156
+ "rules": {
157
+ "rhythmguard/use-scale": [true, { "scale": "auto" }],
158
+ "value-type-custom-property-required-list": [["length"], { "severity": "warning" }]
159
+ }
160
+ }
161
+ ```
148
162
 
149
163
  ## Contributing and support
150
164
 
package/SECURITY.md CHANGED
@@ -8,6 +8,19 @@
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, the rules load that Tailwind config with `require()` to read `theme.spacing`. 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
+ - **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.
20
+ - **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.
21
+ - **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`.
22
+ - **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.
23
+
11
24
  ## Reporting a Vulnerability
12
25
 
13
26
  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:*)
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.17.0",
3
+ "version": "3.19.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"
@@ -160,7 +160,7 @@
160
160
  },
161
161
  "peerDependencies": {
162
162
  "postcss-scss": "^4.0.0",
163
- "stylelint": "^16.0.0 || ^17.0.0",
163
+ "stylelint": "^16.7.0 || ^17.0.0 || ^18.0.0",
164
164
  "stylelint-config-tailwindcss": "^1.0.1",
165
165
  "stylelint-plugin-logical-css": "^2.0.2"
166
166
  },
@@ -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": {
@@ -297,6 +297,14 @@ function createLegacyFindingKey(finding) {
297
297
 
298
298
  function getAuditFailures(report, parsed) {
299
299
  const failures = [];
300
+ const gated = parsed.maxFindings !== null || parsed.minCleanliness !== null || parsed.failOnNewDrift;
301
+ const missing = (report.scanned && report.scanned.stylelintMissing) || 0;
302
+
303
+ // Without Stylelint the stylesheets were not audited, so no gate can pass on
304
+ // what was read: say so and fail, rather than pass on class strings alone.
305
+ if (gated && missing > 0) {
306
+ failures.push(`${missing} stylesheet(s) were not audited because Stylelint is not installed (npm install --save-dev stylelint), so the gate cannot pass`);
307
+ }
300
308
 
301
309
  if (parsed.maxFindings !== null && report.totalWarnings > parsed.maxFindings) {
302
310
  failures.push(`total findings ${report.totalWarnings} exceeds --max-findings ${parsed.maxFindings}`);
@@ -242,6 +242,7 @@ function buildReport({
242
242
  scssFiles = 0,
243
243
  scssSkipped = 0,
244
244
  stylelintIgnored = 0,
245
+ stylelintMissing = 0,
245
246
  templateFiles,
246
247
  tailwindFindings,
247
248
  tokenCandidateMinCount,
@@ -273,9 +274,10 @@ function buildReport({
273
274
  ...tailwindFindings.map((finding) => finding.file),
274
275
  ])).slice(0, 10);
275
276
 
276
- // A stylesheet skipped for want of postcss-scss, or excluded by the project's
277
- // .stylelintignore, was not audited: it is neither scanned nor clean.
278
- const cssFilesScanned = Math.max(0, cssFiles.length - scssSkipped - stylelintIgnored);
277
+ // A stylesheet skipped for want of postcss-scss or of Stylelint itself, or
278
+ // excluded by the project's .stylelintignore, was not audited: it is neither
279
+ // scanned nor clean.
280
+ const cssFilesScanned = Math.max(0, cssFiles.length - scssSkipped - stylelintIgnored - stylelintMissing);
279
281
  const totalFiles = cssFilesScanned + templateFiles.length;
280
282
  const totalWarnings = cssFindings.length + motionFindings.length + tailwindFindings.length;
281
283
  const filesWithIssues = issueFiles.size;
@@ -323,6 +325,8 @@ function buildReport({
323
325
  scssFiles,
324
326
  scssSkipped,
325
327
  stylelintIgnored,
328
+ // Stylesheets found in a project without Stylelint: class strings were audited, these were not.
329
+ stylelintMissing,
326
330
  // Vendored, minified or built stylesheets left out of the audit (#161).
327
331
  nonAuthoredSkipped: nonAuthoredFiles.length,
328
332
  nonAuthoredFiles,
@@ -0,0 +1,84 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * The commands the quickstart, `init` and the audit's text footer print next,
5
+ * built from what the run scanned rather than written as literals, so each one
6
+ * works when pasted: the install line names every package the pasted config
7
+ * needs, the lint glob matches the stylesheets that were found, and the audit
8
+ * command repeats the run's own scale flags (dx-01, dx-05, dx-10, dx-11).
9
+ */
10
+ const path = require('node:path');
11
+
12
+ const { peerDependencies } = require('../../package.json');
13
+
14
+ const SAFE_DIRECTORY = /^[\w.@+-]+$/;
15
+
16
+ function shellQuote(value) {
17
+ return /^[\w./@%+=:,-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
18
+ }
19
+
20
+ /** `npm install` for the Stylelint path: Stylelint at the plugin's peer range, plus what the pasted config extends or parses with. */
21
+ function stylelintInstallLine({ scss = false, tailwindConfig = false } = {}) {
22
+ return [
23
+ 'npm install --save-dev',
24
+ // Double quotes: the range holds spaces and ||, and cmd.exe does not take single quotes.
25
+ `"stylelint@${peerDependencies.stylelint}"`,
26
+ 'stylelint-plugin-rhythmguard',
27
+ ...(tailwindConfig ? ['stylelint-config-tailwindcss'] : []),
28
+ ...(scss ? ['postcss-scss'] : []),
29
+ ].join(' ');
30
+ }
31
+
32
+ /** `npm install` for the class-string path, with the TypeScript parser when the snippet uses it. */
33
+ function eslintInstallLine({ typescript = false } = {}) {
34
+ return ['npm install --save-dev eslint eslint-plugin-rhythmguard', ...(typescript ? ['typescript-eslint'] : [])].join(' ');
35
+ }
36
+
37
+ /**
38
+ * The Stylelint glob for the stylesheets a run found: under their one top-level
39
+ * directory when they share it (`src/**\/*.css`), else from the root, with the
40
+ * extensions that occur (`*.{css,scss}`).
41
+ */
42
+ function lintGlob(cwd, cssFiles) {
43
+ const relative = cssFiles.map((file) => path.relative(cwd, file)).filter((file) => file && !file.startsWith('..'));
44
+ const extensions = [...new Set(relative.map((file) => path.extname(file).slice(1)).filter(Boolean))].sort();
45
+ const pattern = extensions.length > 1 ? `*.{${extensions.join(',')}}` : `*.${extensions[0] || 'css'}`;
46
+ const tops = new Set(relative.map((file) => (file.includes(path.sep) ? file.split(path.sep)[0] : '')));
47
+ const top = tops.size === 1 ? [...tops][0] : '';
48
+ // The glob is printed inside double quotes for pasting, where $(...) and
49
+ // backticks still expand, so a directory name goes in only when it is plain.
50
+ return top && SAFE_DIRECTORY.test(top) ? `${top}/**/${pattern}` : `**/${pattern}`;
51
+ }
52
+
53
+ /** `npx rhythmguard audit <dir>` with the scale flags of the run it describes. */
54
+ function auditCommand({ dir = '.', scale = null, tokenSources = [] } = {}) {
55
+ const scaleArg = Array.isArray(scale) ? scale.join(',') : scale;
56
+ return [
57
+ 'npx rhythmguard audit',
58
+ shellQuote(dir),
59
+ ...(scaleArg ? [`--scale ${shellQuote(String(scaleArg))}`] : []),
60
+ ...tokenSources.map((file) => `--token-source ${shellQuote(file)}`),
61
+ ].join(' ');
62
+ }
63
+
64
+ /**
65
+ * The audit command a CLI run should be repeated with: only the flags the user
66
+ * passed, since anything from .rhythmguardrc.json is read again anyway.
67
+ */
68
+ function auditCommandFromArgs(parsed) {
69
+ const passed = parsed.cliOptions || new Set();
70
+ return auditCommand({
71
+ dir: parsed.dir || '.',
72
+ scale: passed.has('scale') ? parsed.scale : null,
73
+ tokenSources: passed.has('tokenSources') ? parsed.tokenSources.map((entry) => (typeof entry === 'string' ? entry : entry.path)) : [],
74
+ });
75
+ }
76
+
77
+ module.exports = {
78
+ auditCommand,
79
+ auditCommandFromArgs,
80
+ eslintInstallLine,
81
+ lintGlob,
82
+ shellQuote,
83
+ stylelintInstallLine,
84
+ };
@@ -2,25 +2,56 @@
2
2
 
3
3
  const { getAllFindings } = require('./baseline');
4
4
 
5
+ /**
6
+ * GitHub shows at most 10 error and 10 warning annotations per step and drops
7
+ * the rest without a word, so the one line a pull request added was annotation
8
+ * 4,695 of 5,987 (ci-03). The summary comes first; with a baseline only the
9
+ * new findings are annotated, as errors; each type stops at the cap with a
10
+ * notice that says how many were left out. Arrays are walked, not spread:
11
+ * spreading 150,000 findings into push() overflowed the stack (cq-04).
12
+ */
13
+ const ANNOTATIONS_PER_TYPE = 10;
14
+
15
+ function annotation(level, finding, text) {
16
+ return `::${level} file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'rhythmguard')}::${escapeGithubData(text)}`;
17
+ }
18
+
5
19
  function renderGithub(report) {
6
20
  const findings = getAllFindings(report);
7
- const lines = report.baseline
8
- ? [`::notice title=Rhythmguard audit::Since baseline: ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new`]
9
- : [];
10
- // A stylesheet that failed to parse was not audited: an error on its line.
11
- lines.push(...((report.findings && report.findings.parseErrors) || []).map((finding) =>
12
- `::error file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'CssSyntaxError')}::${escapeGithubData(`Not audited: ${finding.text || ''}`)}`,
13
- ));
14
- lines.push(...findings.map((finding) =>
15
- `::warning file=${escapeGithubProperty(finding.file)},line=${finding.line || 1},col=${finding.column || 1},title=${escapeGithubProperty(finding.rule || 'rhythmguard')}::${escapeGithubData(finding.text || '')}`,
16
- ));
21
+ const parseErrors = (report.findings && report.findings.parseErrors) || [];
22
+ const baseline = report.baseline || null;
17
23
  const findingWord = findings.length === 1 ? 'finding' : 'findings';
18
24
  const fileWord = report.filesWithIssues === 1 ? 'file' : 'files';
19
- lines.push(
20
- `::notice title=Rhythmguard audit::${escapeGithubData(
25
+ const lines = [
26
+ `::notice title=Rhythmguard audit::${escapeGithubData([
27
+ ...(baseline ? [`Since baseline: ${baseline.resolvedFindingsCount} resolved, ${baseline.newFindingsCount} new.`] : []),
21
28
  `${findings.length} ${findingWord} across ${report.filesWithIssues} ${fileWord}, ${report.scaleCleanliness}% scale cleanliness`,
22
- )}`,
23
- );
29
+ ].join(' '))}`,
30
+ ];
31
+
32
+ // Errors: stylesheets that could not be parsed, then (with a baseline) new findings.
33
+ const errors = [];
34
+ for (const finding of parseErrors) {
35
+ errors.push(annotation('error', { ...finding, rule: finding.rule || 'CssSyntaxError' }, `Not audited: ${finding.text || ''}`));
36
+ }
37
+ const annotated = baseline ? baseline.newFindings || [] : findings;
38
+ const level = baseline ? 'error' : 'warning';
39
+ const rest = [];
40
+ for (const finding of annotated) {
41
+ rest.push(annotation(level, finding, `${baseline ? 'New since the baseline: ' : ''}${finding.text || ''}`));
42
+ }
43
+ const errorLines = level === 'error' ? [...errors, ...rest] : errors;
44
+ const warningLines = level === 'warning' ? rest : [];
45
+
46
+ for (const group of [errorLines, warningLines]) {
47
+ for (const line of group.slice(0, ANNOTATIONS_PER_TYPE)) {
48
+ lines.push(line);
49
+ }
50
+ }
51
+ const left = Math.max(0, errorLines.length - ANNOTATIONS_PER_TYPE) + Math.max(0, warningLines.length - ANNOTATIONS_PER_TYPE);
52
+ if (left > 0) {
53
+ lines.push(`::notice title=Rhythmguard audit::${escapeGithubData(`${left} more not annotated: GitHub shows ${ANNOTATIONS_PER_TYPE} per type. The full list is in --format markdown or --format json.`)}`);
54
+ }
24
55
  return `${lines.join('\n')}\n`;
25
56
  }
26
57
 
@@ -40,6 +71,7 @@ function escapeGithubProperty(value) {
40
71
  }
41
72
 
42
73
  module.exports = {
74
+ ANNOTATIONS_PER_TYPE,
43
75
  escapeGithubData,
44
76
  escapeGithubProperty,
45
77
  renderGithub,
@@ -1,6 +1,8 @@
1
1
  'use strict';
2
2
 
3
3
  const { sortCountMap } = require('./contract');
4
+ const { auditCommand } = require('./next-steps');
5
+ const { nothingAudited, nothingAuditedReasons } = require('./render-text');
4
6
  const { escapeMarkdown, markdownCode, tableCode } = require('./render-utils');
5
7
 
6
8
  function describeScaleSource(scale) {
@@ -12,13 +14,25 @@ function describeScaleSource(scale) {
12
14
  : scale.source;
13
15
  }
14
16
 
15
- function renderMarkdown(report) {
17
+ /**
18
+ * The report a pull request comment carries. GitHub rejects a comment over
19
+ * 65,536 characters, and on 300 stylesheets this reached 64,473 with the new
20
+ * finding at line 129 (ci-03): new findings now come first, and file lists are
21
+ * cut to five names.
22
+ */
23
+ function renderMarkdown(report, options = {}) {
16
24
  const lines = [
17
25
  '# Rhythmguard Design-System Audit',
18
26
  '',
19
27
  ...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new.`, ''] : []),
20
28
  `Directory: ${markdownCode(report.directory)}`,
21
29
  '',
30
+ ];
31
+ if (nothingAudited(report)) {
32
+ lines.push(`**Nothing was audited:** ${escapeMarkdown(nothingAuditedReasons(report).join('; '))}.`, '');
33
+ }
34
+ appendNewFindingsMarkdown(lines, report);
35
+ lines.push(
22
36
  '## Summary',
23
37
  '',
24
38
  '| Metric | Value |',
@@ -27,6 +41,7 @@ function renderMarkdown(report) {
27
41
  `| Template files scanned | ${report.templateFilesScanned} |`,
28
42
  ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
29
43
  ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
44
+ ...(report.scanned && report.scanned.stylelintMissing > 0 ? [`| Stylesheets not audited (Stylelint is not installed: \`npm install --save-dev stylelint\`) | ${report.scanned.stylelintMissing} |`] : []),
30
45
  ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
31
46
  ...(report.scanned && report.scanned.nonAuthoredSkipped > 0 ? [`| Non-authored stylesheets skipped (vendored, minified or built; --include-non-authored audits them) | ${report.scanned.nonAuthoredSkipped} |`] : []),
32
47
  ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [`| Symbolic links not followed (they point outside the scanned directory) | ${report.scanned.linksOutsideRoot} |`] : []),
@@ -34,7 +49,7 @@ function renderMarkdown(report) {
34
49
  `| Files with issues | ${report.filesWithIssues} |`,
35
50
  `| Total findings | ${report.totalWarnings} |`,
36
51
  `| Scale cleanliness | ${report.scaleCleanliness}% |`,
37
- ];
52
+ );
38
53
 
39
54
  if (report.scale) {
40
55
  lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
@@ -92,7 +107,8 @@ function renderMarkdown(report) {
92
107
  if (report.totalWarnings === 0) {
93
108
  lines.push('- Keep Rhythmguard in CI to prevent new drift.');
94
109
  } else {
95
- lines.push('- Run deterministic autofix for CSS declarations where appropriate.');
110
+ const command = options.auditCommand || auditCommand({ dir: report.directory });
111
+ lines.push(`- Propose one decision per off-scale value with ${markdownCode(`${command} --plan`)}, then rewrite each decided value with ${markdownCode('npx rhythmguard fix <dir> --value <px> --to <step or token>')}. Snapping every value at once can move layout.`);
96
112
  lines.push('- Review Tailwind arbitrary spacing values with UX/design-system owners.');
97
113
  lines.push('- Convert repeated raw on-scale values into existing design tokens.');
98
114
  }
@@ -117,7 +133,7 @@ function appendParseErrorsMarkdown(lines, report) {
117
133
  lines.push('| File | Error |');
118
134
  lines.push('| --- | --- |');
119
135
  for (const finding of errors) {
120
- lines.push(`| ${tableCode(`${finding.file}:${finding.line}:${finding.column}`)} | ${escapeMarkdown(finding.text)} |`);
136
+ lines.push(`| ${tableCode(`${finding.file}:${finding.line}:${finding.column}`)} | ${tableCode(finding.text || '')} |`);
121
137
  }
122
138
  lines.push('');
123
139
  }
@@ -221,7 +237,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
221
237
  lines.push('| Token | Files |');
222
238
  lines.push('| --- | --- |');
223
239
  for (const entry of missingTokens.slice(0, 10)) {
224
- lines.push(`| ${tableCode(entry.token)} | ${tableCode(entry.files.join(', '))} |`);
240
+ lines.push(`| ${tableCode(entry.token)} | ${tableCode(fileList(entry.files))} |`);
225
241
  }
226
242
  lines.push('');
227
243
  }
@@ -243,7 +259,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
243
259
  lines.push('| Value | Count | Files |');
244
260
  lines.push('| --- | ---: | --- |');
245
261
  for (const entry of rawValueCandidates.slice(0, 10)) {
246
- lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(entry.files.join(', '))} |`);
262
+ lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(fileList(entry.files))} |`);
247
263
  }
248
264
  lines.push('');
249
265
  }
@@ -271,6 +287,34 @@ function appendTokenContractMarkdown(lines, tokenContract) {
271
287
  }
272
288
  }
273
289
 
290
+ const NEW_FINDINGS_SHOWN = 25;
291
+ const FILES_SHOWN = 5;
292
+
293
+ /** Five names and a count: a value repeated in 300 files made one table row of 6,900 characters. */
294
+ function fileList(files) {
295
+ const shown = files.slice(0, FILES_SHOWN).join(', ');
296
+ return files.length > FILES_SHOWN ? `${shown}, +${files.length - FILES_SHOWN} more` : shown;
297
+ }
298
+
299
+ function appendNewFindingsMarkdown(lines, report) {
300
+ const fresh = (report.baseline && report.baseline.newFindings) || [];
301
+ if (fresh.length === 0) {
302
+ return;
303
+ }
304
+ lines.push('## New Since the Baseline');
305
+ lines.push('');
306
+ lines.push('| Location | Finding |');
307
+ lines.push('| --- | --- |');
308
+ for (const finding of fresh.slice(0, NEW_FINDINGS_SHOWN)) {
309
+ // A code span: finding text can carry values from the project's source, and this goes into a PR comment.
310
+ lines.push(`| ${tableCode(`${finding.file}:${finding.line}`)} | ${tableCode(finding.text || '')} |`);
311
+ }
312
+ if (fresh.length > NEW_FINDINGS_SHOWN) {
313
+ lines.push(`| ${fresh.length - NEW_FINDINGS_SHOWN} more | see \`--format json\` |`);
314
+ }
315
+ lines.push('');
316
+ }
317
+
274
318
  function appendBaselineMarkdown(lines, report) {
275
319
  if (!report.baseline && !report.baselineWritten) {
276
320
  return;
@@ -288,15 +332,6 @@ function appendBaselineMarkdown(lines, report) {
288
332
  lines.push('');
289
333
  }
290
334
 
291
- if (report.baseline && report.baseline.newFindings.length > 0) {
292
- lines.push('| New finding | Location |');
293
- lines.push('| --- | --- |');
294
- for (const finding of report.baseline.newFindings.slice(0, 10)) {
295
- lines.push(`| ${tableCode(finding.text)} | ${tableCode(`${finding.file}:${finding.line}`)} |`);
296
- }
297
- lines.push('');
298
- }
299
-
300
335
  if (report.baselineWritten) {
301
336
  lines.push(`Baseline written: ${markdownCode(report.baselineWritten.file)}`);
302
337
  lines.push('');