stylelint-plugin-rhythmguard 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-09-06
+
+### Fixed
+
+- The Sass token evaluator bounds map nesting (16 levels) and expression nesting (64 levels). Generated or adversarial input past those limits is skipped like any other expression it cannot evaluate, instead of overflowing the stack and aborting the audit.
+- `scale: "auto"` prefers root-level declarations. When the custom properties in `:root`, `html`, `:host` or `@theme` (through conditional at-rules) form a scale on their own, variables declared inside component selectors no longer join it. Mantine now infers exactly its `--mantine-spacing-*` ladder instead of a mix with `--chip-spacing`. When the root carries no scale, every declaration still counts. ([#54](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/54))
+- `postcss-value-parser` is declared as a runtime dependency. The rules require it at runtime but it was only a dev dependency, resolved through Stylelint's hoisted copy; strict package managers could not install the plugin without it.
+
+### Changed
+
+- Internal architecture, no behaviour change (the 57-repository benchmark check shows zero moved findings): `src/utils` is now `src/core` with domain-named modules; Stylelint-coupled code lives in `src/rules/report.js` and `src/rules/validate.js`; the four rules are assembled from shared primitives (`fixedLengthValue`, `createPropertyScaleResolver`, `withResolvedScale`, `reportValueNode`); the audit uses the same CSS token scanner as token sources; project discovery for `scale: "auto"` is cached per working directory and revalidated by file mtime; audit CLI flags are one option table from which `--help` is rendered. Executable rules for layer direction, cycles, dependency declaration and CJS/ESM parity live under `test/contracts/`. The map is [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+- `src/audit/scan.js` (676 lines) is three modules by responsibility: `scan/files.js`, `scan/stylesheets.js`, `scan/templates.js`.
+- Tests are grouped by what they prove: `test/{unit,rules,cli,api,contracts,compat,bench}`.
+- CI and benchmark workflows cancel superseded runs on the same ref, skip docs-only changes, and can be dispatched by hand.
+
+## [3.3.0] - 2026-09-06
+
+### Fixed
+
+- Whole numbers ending in zero were printed without their zeros: a scale containing `30px` and `60px` produced messages such as `nearest: 3px or 6px`, autofix wrote `3px` for a value snapped to `30px`, and scale inference added phantom small steps (`3px`, `6px`) to every scale that contained `30px` or `60px`. This affected all three Stylelint rules, the ESLint rule's suggested classes, the audit and `scale: "auto"`. Found while reading why GOV.UK's scale came out as `1, 2, 3, 4, 5, 6, 10, 15, ...`. If you use a scale with round-ten values, rerun `--fix` on files that were fixed with an earlier version.
+- `scale: "auto"` accepts tokens named `spacer`, so PatternFly's `--pf-t--global--spacer--*` ladder is read instead of falling back. ([#85](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/85))
+- Token-package discovery reads `@carbon/layout`, where Carbon defines `$spacing-01` to `$spacing-13`. `.scss` files are accepted as token sources, in `scaleSources` and `--token-source` too. ([#87](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/87))
+- `scale: "auto"` and `--scale auto` reject an inferred scale that does not look like one: fewer than three steps, fractional values, no common step (2, 3, 4, 5 or 8), or, in the audit, tokens that come mostly from component files without a near-perfect ladder. The rule then uses the preset and says why in its first message; the audit reports `contracts.scale.rejected` with the source, values and reasons, and the Markdown and text output show it next to the scale source. Component-local variables such as `--chip-spacing: 3px` can no longer become the project scale. ([#88](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/88))
+- Sass spacing maps with one namespace segment before the anchor, such as GOV.UK's `$govuk-spacing-points` and NHS.UK's `$nhsuk-spacing-points`, are read when they hold at least four distinct lengths. Namespaced scalars such as `$dropdown-spacer` and small maps stay excluded, and unitless Sass numbers (mixin parameter defaults such as `$spacing-responsive: 6`, multipliers such as `$spacing-unit: 8`) are no longer taken as lengths. ([#86](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/86))
+- When several Tailwind v4 `--spacing` bases are found, only the first is expanded. A union of ladders from several theme files produced fractional steps that matched nothing on shadcn/ui. ([#89](https://github.com/PetriLahdelma/stylelint-plugin-rhythmguard/issues/89))
+
+### Changed
+
+- The quiet benchmark manifest grew from 20 to 57 repositories: design systems (GOV.UK, NHS.UK, PatternFly, Cloudscape, Angular Material, Ionic, Element Plus, HashiCorp, SAP Fundamental Styles and UI5 Web Components, daisyUI, Skeleton, Semi, n8n, Utrecht, Mozilla Protocol, Foundation, CoreUI, Tabler, AdminLTE, Materialize, Pure, Tachyons) and CSS-heavy applications (Mastodon already; now Forem, Discourse, Zulip, Mattermost, Grafana, Metabase, Directus, Excalidraw, Ghost, Cal.com, VS Code base UI, Docusaurus, VitePress and Starlight themes). Every repository has a pinned snapshot and the State of Spacing edition is regenerated over the full set.
+- `npm run bench:outreach` drafts one audit issue per benchmark repository under `docs/outreach/audits/`; a separate paced posting script runs a per-repository preflight and records every outcome in `docs/outreach/embed-log.md`.
+
 ## [3.2.0] - 2026-09-06
 
 ### Added

package/CONTRIBUTING.md

@@ -10,7 +10,7 @@ Thank you for being here. Rhythmguard is a small, opinionated tool with one job:
 
 **Review a drift list.** Each benchmark repo has a list of findings that heuristics call real drift. Labelling them as real or as an allowance in `benchmarks/quiet/labels/<repo>.json` with a one-line reason turns a heuristic number into a reviewed one, and any systematic pattern you find becomes a candidate default.
 
-**Teach inference a new token source.** Sass variables and maps, token packages, framework theme files. If your scale lives somewhere the tool cannot see, the fix is a parser in `src/utils/token-sources.js` and a test.
+**Teach inference a new token source.** Sass variables and maps, token packages, framework theme files. If your scale lives somewhere the tool cannot see, the fix is a parser in `src/core/token-sources.js` and a test.
 
 **Improve a rule page.** Every rule has a page under `docs/rules/`. A clearer example or a missing edge case is a welcome PR.
 
@@ -27,7 +27,19 @@ npm ci
 npm test
 ```
 
-Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` and take about five seconds.
+Node 20.19 or newer. No build step; the source runs as is. Tests use `node --test` and take about ten seconds. They are grouped by what they prove:
+
+| Folder | Proves | Run one |
+| --- | --- | --- |
+| `test/unit/` | a core primitive (lengths, options, token sources, inference cache) | `node --test test/unit/length-format.test.js` |
+| `test/rules/` | a Stylelint or ESLint rule end to end through the real linter | `node --test test/rules/use-scale.test.js` |
+| `test/cli/` | a command as a user runs it, in a temp directory | `node --test test/cli/audit-cli.test.js` |
+| `test/api/` | the programmatic audit API | |
+| `test/contracts/` | what must stay true for consumers: package exports, CJS/ESM parity, layer rules, rule docs | `node --test test/contracts/architecture.test.js` |
+| `test/compat/` | the Stylelint 16.0.0 floor | `npm run test:compat-floor` |
+| `test/bench/` | the benchmark and report scripts | |
+
+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.
 
 ## The local gate
 
@@ -36,7 +48,7 @@ Run these before you push. They are what CI runs, so a green local run means a g
 ```bash
 npm run lint        # eslint
 npm run typecheck   # the published TypeScript declarations against a consumer file and the examples
-npm test            # 150+ tests, Stylelint 16
+npm test            # 200+ tests, Stylelint 16
 ```
 
 Optional, depending on what you touched:
@@ -54,6 +66,10 @@ If your shell's npm registry is overridden by a corporate `.npmrc`, add `--regis
 
 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 current Stylelint 16, covering lint, typecheck and the test suite. You will see its result on your PR. The full matrix and the benchmark run after merge.
 
+## Where things live
+
+[`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.
+
 ## How we write changes
 
 **Tests first.** Every behaviour change starts with a failing test. If you send a fix without one, expect the review to ask for it; the test is what proves the fix is the right one and keeps it that way.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=5" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
+  <img src="https://raw.githubusercontent.com/petrilahdelma/stylelint-plugin-rhythmguard/main/assets/rhythmguard-banner.svg?v=7" width="100%" alt="Rhythmguard banner showing spacing scale ruler and lint output" />
 </p>
 
 # stylelint-plugin-rhythmguard
@@ -97,6 +97,7 @@ A README badge comes from the same audit: `--format badge` writes a shields.io e
 - [For coding agents](docs/FOR_AGENTS.md): a paste-ready `AGENTS.md` block, installable with `npx rhythmguard init --agents all` for Claude Code, Cursor and Copilot
 - [Quiet benchmark](docs/QUIET_BENCHMARK.md): findings on public design systems, checked on every change
 - [State of Spacing](docs/STATE_OF_SPACING.md): dated editions of the same data, ranked by drift density, with the values and properties that drifted
+- [Architecture](docs/ARCHITECTURE.md): the layers, the rule kit, the invariants and where each is enforced
 - [Product direction](docs/STRATEGY_2026-09.md)
 - Browser playground: [petrilahdelma.github.io/stylelint-plugin-rhythmguard](https://petrilahdelma.github.io/stylelint-plugin-rhythmguard/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-rhythmguard",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "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.",
   "bin": {
     "rhythmguard": "src/cli/index.js"
@@ -108,15 +108,16 @@
     "lint": "eslint .",
     "scales:add": "node scripts/scales/add-scale.mjs",
     "scales:validate": "node scripts/scales/validate-community-scales.mjs",
-    "test": "node --test test/*.test.js",
-    "test:compat-floor": "node --test test/floor-compat.test.js",
-    "test:coverage": "c8 --reporter=text --reporter=lcov node --test test/*.test.js",
+    "test": "node scripts/test.mjs",
+    "test:compat-floor": "node --test test/compat/floor-compat.test.js",
+    "test:coverage": "c8 --reporter=text --reporter=lcov node scripts/test.mjs",
     "test:npm-smoke": "node scripts/ci/npm-registry-smoke.mjs --package stylelint-plugin-rhythmguard --version latest",
     "test:pack-smoke": "node scripts/ci/pack-smoke.mjs",
-    "test:watch": "node --test --watch test/*.test.js",
+    "test:watch": "node scripts/test.mjs --watch",
     "typecheck": "tsc -p tsconfig.typecheck.json",
     "build:agents": "node scripts/build-agents.mjs",
-    "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs"
+    "bench:state-of-spacing": "node scripts/bench/state-of-spacing.mjs",
+    "bench:outreach": "node scripts/bench/outreach.mjs"
   },
   "repository": {
     "type": "git",
@@ -145,7 +146,8 @@
     }
   },
   "dependencies": {
-    "known-css-properties": "^0.37.0"
+    "known-css-properties": "^0.37.0",
+    "postcss-value-parser": "^4.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
@@ -153,7 +155,6 @@
     "c8": "^10.1.3",
     "eslint": "^9.39.5",
     "postcss-scss": "^4.0.9",
-    "postcss-value-parser": "^4.2.0",
     "stylelint": "^16.15.0",
     "stylelint-config-tailwindcss": "^1.0.1",
     "stylelint-plugin-logical-css": "^2.0.2",

package/src/audit/args.js

@@ -3,7 +3,7 @@
 const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
-} = require('../utils/token-sources');
+} = require('../core/token-sources');
 const { BADGE_METRICS } = require('./render-badge');
 const {
   VALID_FORMATS,
@@ -11,325 +11,120 @@ const {
   normalizeIgnorePattern,
 } = require('./shared');
 
-const HELP = `Usage: rhythmguard audit <dir> [options]
-
-Options:
-  --format <text|json|json-v1|markdown|html|github|badge> Output format (default: text)
-                                 github = GitHub Actions workflow-command annotations
-                                 badge = shields.io endpoint JSON for a README badge
-  --badge-metric <drift|findings> Badge value: drift percent or off-scale count (default: drift)
-  --json                         Alias for --format json
-  --markdown                     Alias for --format markdown
-  --schema                       Print the audit JSON schema and exit
-  --output <file>                Write json, markdown, html or badge output to a file
-  --config <file>                Load audit config (default: .rhythmguardrc.json when present)
-  --no-config                    Ignore .rhythmguardrc.json discovery
-  --ignore <pattern>             Exclude root-relative path/glob (repeatable, comma-separated)
-  --ignore-path <file>           Load ignore patterns from file (default: .rhythmguardignore when present)
-  --baseline <file>              Baseline file path (default: .rhythmguard-baseline.json)
-  --write-baseline [file]        Write current findings as a baseline
-  --since-baseline [file]        Compare current findings against a baseline
-  --fail-on-new-drift            Exit 1 when --since-baseline finds new drift
-  --max-findings <number>        Exit 1 when total findings exceed this count
-  --min-cleanliness <percent>    Exit 1 when scale cleanliness is lower than this percent
-  --since <git-ref>              Scan only changed files since a git ref
-  --staged                       Scan only staged files
-  --include-motion               Include opt-in motion duration/easing drift
-  --token-source <file>          External token source (repeatable, comma-separated)
-  --token-source-format <format> Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)
-  --token-kind <kind>            Token kind: spacing, radius, typography, size, motion, all (default: spacing)
-  --token-candidate-min-count <n> Minimum repeated raw value count for token candidates (default: 2)
-  --scale <values|auto>          Comma-separated scale values (default: 0,4,8,12,16,24,32);
-                                 auto infers the scale from token sources, then --space-*/--spacing-*
-                                 custom properties and Sass variables in scanned CSS/SCSS, then
-                                 installed design-token packages, and reports where it came from
-  --base-font-size <number>      px base for rem/em conversion (default: 16)
-
-Scans .css files, and .scss files when postcss-scss is installed. Reports drift by
-value, by property and by file; text output prints histograms, markdown is PR-ready,
-json is the stable 2.0 contract.
-`;
+/**
+ * Every audit flag is one entry here. `kind` says whether the flag takes a
+ * value (`value`), may take one (`optional`: the next argument is consumed
+ * unless it starts with a dash), or is a switch (`flag`). `apply` writes the
+ * parsed result; `cliOptions` records which keys the command line set so the
+ * config file loader can tell an explicit value from a default. The help text
+ * is rendered from this table, so a flag cannot exist without documentation.
+ */
+const setFrom = (parsed, key) => parsed.cliOptions.add(key);
+
+const OPTIONS = [
+  { flag: '--format', kind: 'value', value: '<text|json|json-v1|markdown|html|github|badge>', help: ['Output format (default: text)', 'github = GitHub Actions workflow-command annotations', 'badge = shields.io endpoint JSON for a README badge'],
+    apply: (p, raw) => { p.format = String(raw || '').toLowerCase(); } },
+  { flag: '--badge-metric', kind: 'value', value: '<drift|findings>', help: 'Badge value: drift percent or off-scale count (default: drift)',
+    apply: (p, raw) => { p.badgeMetric = String(raw || '').toLowerCase(); } },
+  { flag: '--json', kind: 'flag', help: 'Alias for --format json', apply: (p) => { p.format = 'json'; } },
+  { flag: '--markdown', kind: 'flag', help: 'Alias for --format markdown', apply: (p) => { p.format = 'markdown'; } },
+  { flag: '--schema', kind: 'flag', help: 'Print the audit JSON schema and exit', apply: (p) => { p.schema = true; p.format = 'json'; } },
+  { flag: '--output', kind: 'value', value: '<file>', help: 'Write json, markdown, html or badge output to a file',
+    apply: (p, raw) => { p.outputPath = parsePathOption(raw, '--output'); setFrom(p, 'outputPath'); } },
+  { flag: '--config', kind: 'value', value: '<file>', help: 'Load audit config (default: .rhythmguardrc.json when present)',
+    apply: (p, raw) => { p.configPath = parsePathOption(raw, '--config'); p.configExplicit = true; } },
+  { flag: '--no-config', kind: 'flag', help: 'Ignore .rhythmguardrc.json discovery', apply: (p) => { p.noConfig = true; } },
+  { flag: '--ignore', kind: 'value', value: '<pattern>', help: 'Exclude root-relative path/glob (repeatable, comma-separated)',
+    apply: (p, raw) => { p.ignorePatterns.push(...parseIgnorePatterns(raw)); setFrom(p, 'ignore'); } },
+  { flag: '--ignore-path', kind: 'value', value: '<file>', help: 'Load ignore patterns from file (default: .rhythmguardignore when present)',
+    apply: (p, raw) => { p.ignorePath = parsePathOption(raw, '--ignore-path'); setFrom(p, 'ignorePath'); } },
+  { flag: '--baseline', kind: 'value', value: '<file>', help: 'Baseline file path (default: .rhythmguard-baseline.json)',
+    apply: (p, raw) => { p.baselinePath = parsePathOption(raw, '--baseline'); setFrom(p, 'baselinePath'); } },
+  { flag: '--write-baseline', kind: 'optional', value: '[file]', help: 'Write current findings as a baseline',
+    apply: (p, raw) => { p.writeBaseline = true; setFrom(p, 'writeBaseline'); if (raw !== undefined) { p.baselinePath = parsePathOption(raw, '--write-baseline'); setFrom(p, 'baselinePath'); } } },
+  { flag: '--since-baseline', kind: 'optional', value: '[file]', help: 'Compare current findings against a baseline',
+    apply: (p, raw) => { p.sinceBaseline = true; setFrom(p, 'sinceBaseline'); if (raw !== undefined) { p.baselinePath = parsePathOption(raw, '--since-baseline'); setFrom(p, 'baselinePath'); } } },
+  { flag: '--fail-on-new-drift', kind: 'flag', help: 'Exit 1 when --since-baseline finds new drift',
+    apply: (p) => { p.failOnNewDrift = true; setFrom(p, 'failOnNewDrift'); } },
+  { flag: '--max-findings', kind: 'value', value: '<number>', help: 'Exit 1 when total findings exceed this count',
+    apply: (p, raw) => { p.maxFindings = parseNonNegativeInteger(raw, '--max-findings'); setFrom(p, 'maxFindings'); } },
+  { flag: '--min-cleanliness', kind: 'value', value: '<percent>', help: 'Exit 1 when scale cleanliness is lower than this percent',
+    apply: (p, raw) => { p.minCleanliness = parsePercentage(raw, '--min-cleanliness'); setFrom(p, 'minCleanliness'); } },
+  { flag: '--since', kind: 'value', value: '<git-ref>', help: 'Scan only changed files since a git ref',
+    apply: (p, raw) => { p.since = parsePathOption(raw, '--since'); setFrom(p, 'since'); } },
+  { flag: '--staged', kind: 'flag', help: 'Scan only staged files', apply: (p) => { p.staged = true; setFrom(p, 'staged'); } },
+  { flag: '--include-motion', kind: 'flag', help: 'Include opt-in motion duration/easing drift',
+    apply: (p) => { p.includeMotion = true; setFrom(p, 'includeMotion'); } },
+  { flag: '--token-source', kind: 'value', value: '<file>', help: 'External token source (repeatable, comma-separated)',
+    apply: (p, raw) => { p.tokenSources.push(...parseTokenSourcePaths(raw)); setFrom(p, 'tokenSources'); } },
+  { flag: '--token-source-format', kind: 'value', value: '<format>', help: 'Token source format: auto, css, flat-json, style-dictionary, dtcg (default: auto)',
+    apply: (p, raw) => { p.tokenSourceFormat = normalizeTokenSourceFormat(raw); setFrom(p, 'tokenSourceFormat'); } },
+  { flag: '--token-kind', kind: 'value', value: '<kind>', help: 'Token kind: spacing, radius, typography, size, motion, all (default: spacing)',
+    apply: (p, raw) => { p.tokenKind = normalizeTokenKind(raw); setFrom(p, 'tokenKind'); } },
+  { flag: '--token-candidate-min-count', kind: 'value', value: '<n>', help: 'Minimum repeated raw value count for token candidates (default: 2)',
+    apply: (p, raw) => { p.tokenCandidateMinCount = parsePositiveInteger(raw, '--token-candidate-min-count'); setFrom(p, 'tokenCandidateMinCount'); } },
+  { flag: '--scale', kind: 'value', value: '<values|auto>', help: ['Comma-separated scale values (default: 0,4,8,12,16,24,32);', 'auto infers the scale from token sources, then --space-*/--spacing-*', 'custom properties and Sass variables in scanned CSS/SCSS, then', 'installed design-token packages, and reports where it came from'],
+    apply: (p, raw) => { p.scale = parseScale(raw); setFrom(p, 'scale'); } },
+  { flag: '--base-font-size', kind: 'value', value: '<number>', help: 'px base for rem/em conversion (default: 16)',
+    apply: (p, raw) => { p.baseFontSize = parseBaseFontSize(raw); setFrom(p, 'baseFontSize'); } },
+  { flag: '--help', alias: '-h', kind: 'flag', help: 'Show this help message', apply: (p) => { p.help = true; } },
+];
+
+const HELP_COLUMN = 33;
+
+function renderHelp() {
+  const lines = ['Usage: rhythmguard audit <dir> [options]', '', 'Options:'];
+  for (const option of OPTIONS) {
+    const label = `  ${option.flag}${option.value ? ` ${option.value}` : ''}`;
+    const help = Array.isArray(option.help) ? option.help : [option.help];
+    lines.push(`${label.padEnd(HELP_COLUMN)}${label.length >= HELP_COLUMN ? ' ' : ''}${help[0]}`);
+    for (const extra of help.slice(1)) {
+      lines.push(`${''.padEnd(HELP_COLUMN)}${extra}`);
+    }
+  }
+  lines.push(
+    '',
+    'Scans .css files, and .scss files when postcss-scss is installed. Reports drift by',
+    'value, by property and by file; text output prints histograms, markdown is PR-ready,',
+    'json is the stable 2.0 contract.',
+    '',
+  );
+  return lines.join('\n');
+}
+
+const HELP = renderHelp();
+
+function findOption(arg) {
+  return OPTIONS.find((option) => option.flag === arg || option.alias === arg) || null;
+}
 
 function parseArgs(argv) {
   const parsed = createDefaultAuditOptions();
 
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
+    const equals = arg.indexOf('=');
+    const inline = arg.startsWith('--') && equals !== -1 ? findOption(arg.slice(0, equals)) : null;
 
-    if (arg === '--help' || arg === '-h') {
-      parsed.help = true;
-      continue;
-    }
-
-    if (arg === '--schema') {
-      parsed.schema = true;
-      parsed.format = 'json';
-      continue;
-    }
-
-    if (arg === '--json') {
-      parsed.format = 'json';
-      continue;
-    }
-
-    if (arg === '--markdown') {
-      parsed.format = 'markdown';
-      continue;
-    }
-
-    if (arg === '--output') {
-      parsed.outputPath = parsePathOption(argv[++index], '--output');
-      parsed.cliOptions.add('outputPath');
+    if (inline && inline.kind !== 'flag') {
+      inline.apply(parsed, arg.slice(equals + 1));
       continue;
     }
 
-    if (arg.startsWith('--output=')) {
-      parsed.outputPath = parsePathOption(arg.slice('--output='.length), '--output');
-      parsed.cliOptions.add('outputPath');
-      continue;
-    }
-
-    if (arg === '--ignore') {
-      parsed.ignorePatterns.push(...parseIgnorePatterns(argv[++index]));
-      parsed.cliOptions.add('ignore');
-      continue;
-    }
-
-    if (arg.startsWith('--ignore=')) {
-      parsed.ignorePatterns.push(...parseIgnorePatterns(arg.slice('--ignore='.length)));
-      parsed.cliOptions.add('ignore');
-      continue;
-    }
-
-    if (arg === '--config') {
-      parsed.configPath = parsePathOption(argv[++index], '--config');
-      parsed.configExplicit = true;
-      continue;
-    }
-
-    if (arg.startsWith('--config=')) {
-      parsed.configPath = parsePathOption(arg.slice('--config='.length), '--config');
-      parsed.configExplicit = true;
-      continue;
-    }
-
-    if (arg === '--no-config') {
-      parsed.noConfig = true;
-      continue;
-    }
-
-    if (arg === '--ignore-path') {
-      parsed.ignorePath = parsePathOption(argv[++index], '--ignore-path');
-      parsed.cliOptions.add('ignorePath');
-      continue;
-    }
-
-    if (arg.startsWith('--ignore-path=')) {
-      parsed.ignorePath = parsePathOption(arg.slice('--ignore-path='.length), '--ignore-path');
-      parsed.cliOptions.add('ignorePath');
-      continue;
-    }
-
-    if (arg === '--baseline') {
-      parsed.baselinePath = parsePathOption(argv[++index], '--baseline');
-      parsed.cliOptions.add('baselinePath');
-      continue;
-    }
-
-    if (arg.startsWith('--baseline=')) {
-      parsed.baselinePath = parsePathOption(arg.slice('--baseline='.length), '--baseline');
-      parsed.cliOptions.add('baselinePath');
-      continue;
-    }
-
-    if (arg === '--write-baseline') {
-      parsed.writeBaseline = true;
-      parsed.cliOptions.add('writeBaseline');
-      if (argv[index + 1] && !argv[index + 1].startsWith('-')) {
-        parsed.baselinePath = parsePathOption(argv[++index], '--write-baseline');
-        parsed.cliOptions.add('baselinePath');
+    const option = findOption(arg);
+    if (option) {
+      if (option.kind === 'flag') {
+        option.apply(parsed);
+      } else if (option.kind === 'value') {
+        option.apply(parsed, argv[++index]);
+      } else if (argv[index + 1] !== undefined && !argv[index + 1].startsWith('-')) {
+        option.apply(parsed, argv[++index]);
+      } else {
+        option.apply(parsed, undefined);
       }
       continue;
     }
 
-    if (arg.startsWith('--write-baseline=')) {
-      parsed.writeBaseline = true;
-      parsed.baselinePath = parsePathOption(arg.slice('--write-baseline='.length), '--write-baseline');
-      parsed.cliOptions.add('writeBaseline');
-      parsed.cliOptions.add('baselinePath');
-      continue;
-    }
-
-    if (arg === '--since-baseline') {
-      parsed.sinceBaseline = true;
-      parsed.cliOptions.add('sinceBaseline');
-      if (argv[index + 1] && !argv[index + 1].startsWith('-')) {
-        parsed.baselinePath = parsePathOption(argv[++index], '--since-baseline');
-        parsed.cliOptions.add('baselinePath');
-      }
-      continue;
-    }
-
-    if (arg.startsWith('--since-baseline=')) {
-      parsed.sinceBaseline = true;
-      parsed.baselinePath = parsePathOption(arg.slice('--since-baseline='.length), '--since-baseline');
-      parsed.cliOptions.add('sinceBaseline');
-      parsed.cliOptions.add('baselinePath');
-      continue;
-    }
-
-    if (arg === '--fail-on-new-drift') {
-      parsed.failOnNewDrift = true;
-      parsed.cliOptions.add('failOnNewDrift');
-      continue;
-    }
-
-    if (arg === '--max-findings') {
-      parsed.maxFindings = parseNonNegativeInteger(argv[++index], '--max-findings');
-      parsed.cliOptions.add('maxFindings');
-      continue;
-    }
-
-    if (arg.startsWith('--max-findings=')) {
-      parsed.maxFindings = parseNonNegativeInteger(arg.slice('--max-findings='.length), '--max-findings');
-      parsed.cliOptions.add('maxFindings');
-      continue;
-    }
-
-    if (arg === '--min-cleanliness') {
-      parsed.minCleanliness = parsePercentage(argv[++index], '--min-cleanliness');
-      parsed.cliOptions.add('minCleanliness');
-      continue;
-    }
-
-    if (arg.startsWith('--min-cleanliness=')) {
-      parsed.minCleanliness = parsePercentage(
-        arg.slice('--min-cleanliness='.length),
-        '--min-cleanliness',
-      );
-      parsed.cliOptions.add('minCleanliness');
-      continue;
-    }
-
-    if (arg === '--since') {
-      parsed.since = parsePathOption(argv[++index], '--since');
-      parsed.cliOptions.add('since');
-      continue;
-    }
-
-    if (arg.startsWith('--since=')) {
-      parsed.since = parsePathOption(arg.slice('--since='.length), '--since');
-      parsed.cliOptions.add('since');
-      continue;
-    }
-
-    if (arg === '--staged') {
-      parsed.staged = true;
-      parsed.cliOptions.add('staged');
-      continue;
-    }
-
-    if (arg === '--include-motion') {
-      parsed.includeMotion = true;
-      parsed.cliOptions.add('includeMotion');
-      continue;
-    }
-
-    if (arg === '--token-source') {
-      parsed.tokenSources.push(...parseTokenSourcePaths(argv[++index]));
-      parsed.cliOptions.add('tokenSources');
-      continue;
-    }
-
-    if (arg.startsWith('--token-source=')) {
-      parsed.tokenSources.push(...parseTokenSourcePaths(arg.slice('--token-source='.length)));
-      parsed.cliOptions.add('tokenSources');
-      continue;
-    }
-
-    if (arg === '--token-source-format') {
-      parsed.tokenSourceFormat = normalizeTokenSourceFormat(argv[++index]);
-      parsed.cliOptions.add('tokenSourceFormat');
-      continue;
-    }
-
-    if (arg.startsWith('--token-source-format=')) {
-      parsed.tokenSourceFormat = normalizeTokenSourceFormat(arg.slice('--token-source-format='.length));
-      parsed.cliOptions.add('tokenSourceFormat');
-      continue;
-    }
-
-    if (arg === '--token-kind') {
-      parsed.tokenKind = normalizeTokenKind(argv[++index]);
-      parsed.cliOptions.add('tokenKind');
-      continue;
-    }
-
-    if (arg.startsWith('--token-kind=')) {
-      parsed.tokenKind = normalizeTokenKind(arg.slice('--token-kind='.length));
-      parsed.cliOptions.add('tokenKind');
-      continue;
-    }
-
-    if (arg === '--token-candidate-min-count') {
-      parsed.tokenCandidateMinCount = parsePositiveInteger(argv[++index], '--token-candidate-min-count');
-      parsed.cliOptions.add('tokenCandidateMinCount');
-      continue;
-    }
-
-    if (arg.startsWith('--token-candidate-min-count=')) {
-      parsed.tokenCandidateMinCount = parsePositiveInteger(
-        arg.slice('--token-candidate-min-count='.length),
-        '--token-candidate-min-count',
-      );
-      parsed.cliOptions.add('tokenCandidateMinCount');
-      continue;
-    }
-
-    if (arg === '--badge-metric') {
-      parsed.badgeMetric = String(argv[++index] || '').toLowerCase();
-      continue;
-    }
-
-    if (arg.startsWith('--badge-metric=')) {
-      parsed.badgeMetric = arg.slice('--badge-metric='.length).toLowerCase();
-      continue;
-    }
-
-    if (arg === '--format') {
-      parsed.format = String(argv[++index] || '').toLowerCase();
-      continue;
-    }
-
-    if (arg.startsWith('--format=')) {
-      parsed.format = arg.slice('--format='.length).toLowerCase();
-      continue;
-    }
-
-    if (arg === '--scale') {
-      parsed.scale = parseScale(argv[++index]);
-      parsed.cliOptions.add('scale');
-      continue;
-    }
-
-    if (arg.startsWith('--scale=')) {
-      parsed.scale = parseScale(arg.slice('--scale='.length));
-      parsed.cliOptions.add('scale');
-      continue;
-    }
-
-    if (arg === '--base-font-size') {
-      parsed.baseFontSize = parseBaseFontSize(argv[++index]);
-      parsed.cliOptions.add('baseFontSize');
-      continue;
-    }
-
-    if (arg.startsWith('--base-font-size=')) {
-      parsed.baseFontSize = parseBaseFontSize(arg.slice('--base-font-size='.length));
-      parsed.cliOptions.add('baseFontSize');
-      continue;
-    }
-
     if (!arg.startsWith('-') && !parsed.dir) {
       parsed.dir = arg;
       continue;
@@ -339,7 +134,7 @@ function parseArgs(argv) {
   }
 
   if (!VALID_FORMATS.has(parsed.format)) {
-    throw new Error(`Invalid format "${parsed.format}". Expected text, json, json-v1, markdown, html, or github.`);
+    throw new Error(`Invalid format "${parsed.format}". Expected ${Array.from(VALID_FORMATS).join(', ')}.`);
   }
 
   if (!BADGE_METRICS.has(parsed.badgeMetric)) {
@@ -459,6 +254,7 @@ function parseBaseFontSize(raw) {
 }
 
 module.exports = {
+  OPTIONS,
   HELP,
   parseArgs,
   parseBaseFontSize,

package/src/audit/config.js

@@ -5,7 +5,7 @@ const path = require('node:path');
 const {
   normalizeTokenKind,
   normalizeTokenSourceFormat,
-} = require('../utils/token-sources');
+} = require('../core/token-sources');
 const {
   parseBaseFontSize,
   parseNonNegativeInteger,