stylelint-plugin-rhythmguard 3.12.0 → 3.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +1 -1
  3. package/package.json +23 -1
  4. package/src/audit/args.js +23 -4
  5. package/src/audit/baseline.js +15 -2
  6. package/src/audit/codemod.js +56 -5
  7. package/src/audit/config.js +2 -1
  8. package/src/audit/contract.js +3 -0
  9. package/src/audit/decisions.js +45 -16
  10. package/src/audit/render-markdown.js +22 -21
  11. package/src/audit/render-text.js +4 -0
  12. package/src/audit/render-utils.js +28 -1
  13. package/src/audit/report.js +16 -2
  14. package/src/audit/scan/files.js +139 -30
  15. package/src/audit/token-chains.js +4 -1
  16. package/src/audit/token-ladders.js +23 -2
  17. package/src/cli/doctor.js +58 -6
  18. package/src/cli/fix.js +7 -6
  19. package/src/cli/index.js +2 -2
  20. package/src/cli/init.js +41 -5
  21. package/src/cli/quickstart.js +46 -8
  22. package/src/configs/embed.js +2 -0
  23. package/src/configs/motion.js +1 -0
  24. package/src/configs/recommended.js +1 -0
  25. package/src/configs/strict.js +1 -0
  26. package/src/configs/tailwind.js +1 -0
  27. package/src/core/decisions.js +2 -1
  28. package/src/core/json.js +25 -0
  29. package/src/core/length.js +11 -0
  30. package/src/core/options.js +39 -20
  31. package/src/core/scale-inference.js +78 -23
  32. package/src/core/tailwind-class-analysis.js +3 -2
  33. package/src/core/token-map.js +2 -1
  34. package/src/core/token-sources.js +143 -14
  35. package/src/eslint/index.js +14 -8
  36. package/src/eslint/rules/tailwind-class-use-motion-scale.js +1 -0
  37. package/src/eslint/rules/tailwind-class-use-scale.js +1 -0
  38. package/src/rules/no-offscale-transform/index.js +58 -53
  39. package/src/rules/prefer-token/index.js +31 -46
  40. package/src/rules/use-motion-scale/index.js +14 -1
  41. package/src/rules/use-scale/index.js +75 -102
  42. package/src/rules/validate.js +13 -4
  43. package/types/__checks__/consumer.ts +20 -1
  44. package/types/__checks__/eslint-config.ts +8 -0
  45. package/types/__checks__/shipped-configs.ts +96 -0
  46. package/types/audit.d.ts +103 -16
  47. package/types/index.d.ts +15 -0
  48. package/types/shared.d.ts +126 -20
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Compile-time check that every config the package ships fits the public
3
+ * Stylelint config type (#280). Each src/configs/*.js declares that type in a
4
+ * JSDoc `@type` and is type-checked itself (tsconfig.typecheck.json includes
5
+ * src/configs), so an option the types lack fails `npm run typecheck`. A
6
+ * contract test keeps this list and the annotations in step with src/configs.
7
+ * Nothing here runs; it only has to type-check.
8
+ */
9
+ import type {
10
+ RhythmguardMotionRuleOptions,
11
+ RhythmguardPreferTokenOptions,
12
+ RhythmguardRuleOptions,
13
+ RhythmguardStylelintConfig,
14
+ RhythmguardTransformRuleOptions,
15
+ RhythmguardUseScaleOptions,
16
+ } from 'stylelint-plugin-rhythmguard';
17
+ import embed from '../../src/configs/embed.js';
18
+ import motion from '../../src/configs/motion.js';
19
+ import recommended from '../../src/configs/recommended.js';
20
+ import strict from '../../src/configs/strict.js';
21
+ import tailwind from '../../src/configs/tailwind.js';
22
+
23
+ const shipped: Record<'embed' | 'motion' | 'recommended' | 'strict' | 'tailwind', RhythmguardStylelintConfig> = {
24
+ embed,
25
+ motion,
26
+ recommended,
27
+ strict,
28
+ tailwind,
29
+ };
30
+
31
+ // Stylelint's own secondary options sit next to the rule's options.
32
+ const withStylelintOptions: RhythmguardRuleOptions = {
33
+ disableFix: true,
34
+ message: (value: string) => `Spacing ${value} is off the scale`,
35
+ reportDisables: true,
36
+ severity: 'warning',
37
+ url: 'https://example.com/spacing',
38
+ };
39
+
40
+ const useScale: RhythmguardUseScaleOptions = {
41
+ allowNegative: false,
42
+ allowPercentages: true,
43
+ enforceInsideMathFunctions: true,
44
+ fixToScale: false,
45
+ ignoreMathFunctionArguments: { clamp: [2] },
46
+ ignoreValues: ['auto'],
47
+ mathFunctionArguments: { calc: [1] },
48
+ propertyGroups: ['spacing', 'radius'],
49
+ propertyScales: { '/^margin/': { preset: 'rhythmic-4' }, gap: [0, 8, 16], padding: 'rhythmic-8' },
50
+ scales: { radius: [0, 2, 4], typography: 'auto' },
51
+ tokenFunctions: ['var', 'theme'],
52
+ unitStrategy: 'exact',
53
+ units: ['px', 'vw'],
54
+ };
55
+
56
+ const transform: RhythmguardTransformRuleOptions = { allowNegative: true, fixWith: 'token', tokenPattern: '^--space-' };
57
+
58
+ const preferToken: RhythmguardPreferTokenOptions = {
59
+ allowNumericScale: true,
60
+ tokenMap: { '16px': 'var(--space-4)' },
61
+ tokenMapFile: './tokens.json',
62
+ };
63
+
64
+ const motionOptions: RhythmguardMotionRuleOptions = {
65
+ durationScale: [0, 100, 200],
66
+ durationUnits: ['ms'],
67
+ easingTokenMap: { 'cubic-bezier(.2,0,0,1)': 'var(--ease-standard)' },
68
+ fixToScale: false,
69
+ severity: 'error',
70
+ };
71
+
72
+ const perRule: RhythmguardStylelintConfig = {
73
+ rules: {
74
+ 'rhythmguard/no-offscale-transform': [true, transform],
75
+ 'rhythmguard/prefer-token': [true, preferToken],
76
+ 'rhythmguard/use-motion-scale': [true, motionOptions],
77
+ 'rhythmguard/use-scale': [true, useScale],
78
+ 'other-plugin/rule': [true],
79
+ },
80
+ };
81
+
82
+ const motionOnScaleRule: RhythmguardStylelintConfig = {
83
+ // @ts-expect-error durationScale belongs to use-motion-scale, not use-scale.
84
+ rules: { 'rhythmguard/use-scale': [true, { durationScale: [100] }] },
85
+ };
86
+
87
+ const unknownOption: RhythmguardUseScaleOptions = {
88
+ // @ts-expect-error not an option: Stylelint rejects unknown option names.
89
+ includeMathFunctions: true,
90
+ };
91
+
92
+ void shipped;
93
+ void withStylelintOptions;
94
+ void perRule;
95
+ void motionOnScaleRule;
96
+ void unknownOption;
package/types/audit.d.ts CHANGED
@@ -18,30 +18,47 @@ export interface AuditTokenSource {
18
18
  file?: string;
19
19
  format?: AuditTokenSourceFormat;
20
20
  path?: string;
21
+ /** Regex for token names in this file, overriding the kind matcher. */
22
+ tokenPattern?: string;
21
23
  }
22
24
 
25
+ /**
26
+ * Options for `createAuditReport`. A key set to `undefined` counts as omitted.
27
+ * `.rhythmguardrc.json` fills in what the options leave out, unless `noConfig`.
28
+ * The gates and output options of `rhythmguard audit` (`format`, `outputPath`,
29
+ * `maxFindings`, `minCleanliness`, `failOnNewDrift`, `badgeMetric`) belong to
30
+ * the CLI: `createAuditReport` reads none of them. Check the returned report
31
+ * instead, for example `report.summary.totalFindings` or `report.baseline`.
32
+ */
23
33
  export interface AuditOptions {
24
34
  baseFontSize?: number;
35
+ /** Baseline file read with `sinceBaseline` and written with `writeBaseline`. Default `.rhythmguard-baseline.json`. */
25
36
  baselinePath?: string;
26
37
  /** Path to a `.rhythmguardrc.json`-style config. Defaults to `.rhythmguardrc.json` in `cwd`. */
27
38
  configPath?: string;
28
39
  dir?: string;
40
+ /** @deprecated CLI only (`--fail-on-new-drift`): `createAuditReport` ignores it. Read `report.baseline.newFindingsCount`. */
29
41
  failOnNewDrift?: boolean;
30
- /** Badge value when `format` is "badge": drift percent or off-scale count. */
42
+ /** @deprecated CLI only (`--badge-metric`): `createAuditReport` ignores it. */
31
43
  badgeMetric?: "drift" | "findings";
44
+ /** @deprecated CLI only (`--format`): `createAuditReport` returns the report object, not rendered output. */
32
45
  format?: "json" | "json-v1" | "markdown" | "text" | "html" | "github" | "badge";
33
46
  ignorePath?: string;
34
47
  ignorePatterns?: string[];
35
48
  /** Check clamp() bounds and min()/max() arguments against the scale (equivalent to `--check-math-bounds`). */
36
49
  checkMathBounds?: boolean;
37
50
  includeMotion?: boolean;
51
+ /** Smallest gap in px between neighbouring steps of a token ladder (`audit.ladders.minStepPx`). Default 2. */
52
+ ladderMinStepPx?: number;
38
53
  /** A scale per property group (`spacing`, `radius`, `size`, `typography`): values, a preset name or "auto". Each group named is also checked. */
39
54
  scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", Array<number | string> | string | { preset?: string; scale?: Array<number | string>; customScale?: Array<number | string> }>>;
55
+ /** @deprecated CLI only (`--max-findings`): `createAuditReport` ignores it. Compare `report.summary.totalFindings`. */
40
56
  maxFindings?: number;
57
+ /** @deprecated CLI only (`--min-cleanliness`): `createAuditReport` ignores it. Compare `report.summary.scaleCleanliness`. */
41
58
  minCleanliness?: number;
42
59
  /** Skip config discovery entirely (equivalent to `--no-config`). */
43
60
  noConfig?: boolean;
44
- /** Write rendered output to this file instead of stdout (equivalent to `--output`). */
61
+ /** @deprecated CLI only (`--output`): `createAuditReport` writes nothing. */
45
62
  outputPath?: string;
46
63
  /** Explicit scale values, or `"auto"` to infer from token sources, then scanned CSS, then the default. */
47
64
  scale?: Array<number | string> | "auto";
@@ -52,20 +69,34 @@ export interface AuditOptions {
52
69
  tokenKind?: AuditTokenKind;
53
70
  /** Format applied to `tokenSources` entries that do not declare their own. */
54
71
  tokenSourceFormat?: AuditTokenSourceFormat | "auto";
55
- tokenSources?: AuditTokenSource[];
72
+ /** Token files: paths, or entries with their own format and base directory. */
73
+ tokenSources?: Array<string | AuditTokenSource>;
56
74
  writeBaseline?: boolean;
57
75
  }
58
76
 
59
77
  export interface AuditSummary {
60
- cleanliness: number;
61
- filesWithFindings: number;
62
- findingCount: number;
63
- motionFindingCount?: number;
78
+ /** Off-scale and token findings in stylesheets. */
79
+ cssWarnings: number;
80
+ /** Audited files with at least one finding. */
81
+ filesWithIssues: number;
82
+ missingTokens: number;
83
+ motionFindings: number;
84
+ /** With `sinceBaseline`: findings not in the baseline. */
85
+ newFindings?: number;
64
86
  /** Stylesheets that could not be parsed. They are not findings and are left out of cleanliness. */
65
- parseErrors?: number;
87
+ parseErrors: number;
88
+ rawValueCandidates: number;
89
+ rawValueMatches: number;
90
+ /** With `sinceBaseline`: baseline findings no longer present. */
91
+ resolvedFindings?: number;
66
92
  /** Share of audited files with no finding, rounded down, so it is never 100 while a file has a finding. */
67
- scaleCleanliness?: number;
68
- tokenOpportunityCount?: number;
93
+ scaleCleanliness: number;
94
+ tailwindArbitrarySpacing: number;
95
+ tokenOpportunities: number;
96
+ tokenSources: number;
97
+ /** Every finding: stylesheets, class strings and motion. */
98
+ totalFindings: number;
99
+ unusedTokens: number;
69
100
  [key: string]: unknown;
70
101
  }
71
102
 
@@ -87,27 +118,53 @@ export interface AuditScanned {
87
118
  export interface AuditFinding {
88
119
  column?: number;
89
120
  file: string;
121
+ /** Class strings: the fixed class, or null when there is no safe fix. */
122
+ fixedToken?: string | null;
90
123
  key?: string;
91
124
  line?: number;
92
- message: string;
125
+ /** Class strings: the two nearest scale steps, or null. */
126
+ nearest?: { lower: string; upper: string } | null;
93
127
  /** CSS property of the declaration, recovered from the source. Null when the position is not inside a declaration. CSS findings only. */
94
128
  property?: string | null;
129
+ /** Class strings: the arbitrary value inside the brackets. */
130
+ rawValue?: string;
95
131
  rule?: string;
96
- /** "off-scale", "token-opportunity", "motion-duration", "motion-easing", or "parse-error" for a stylesheet that could not be parsed. */
132
+ /** The finding's message, as the rule reports it. */
133
+ text: string;
134
+ /** Class strings: the whole class, with variants. */
135
+ token?: string;
136
+ /**
137
+ * "off-scale", "token-opportunity", "motion-duration", "motion-easing", "tailwind-arbitrary-spacing",
138
+ * "tailwind-motion-duration", "tailwind-motion-easing", or "parse-error" for a stylesheet that could not be parsed.
139
+ */
97
140
  type: string;
141
+ /** Class strings: the utility, such as `p` or `-mt`. */
142
+ utility?: string;
98
143
  value?: string | null;
99
144
  [key: string]: unknown;
100
145
  }
101
146
 
102
147
  export interface AuditBaselineComparison {
103
148
  baselineFindings: number;
149
+ /** The baseline file, relative to the working directory. */
150
+ file: string;
104
151
  newFindings: AuditFinding[];
105
152
  newFindingsCount: number;
106
- resolvedFindings: AuditFinding[];
107
153
  resolvedFindingsCount: number;
108
154
  [key: string]: unknown;
109
155
  }
110
156
 
157
+ /** What the audit scanned: the whole directory, or files changed since a ref or staged. */
158
+ export interface AuditScanScope {
159
+ changedFiles?: number;
160
+ mode: "full" | "since" | "staged";
161
+ since?: string | null;
162
+ [key: string]: unknown;
163
+ }
164
+
165
+ /** The config file the audit read, or null when there was none or `noConfig` was set. */
166
+ export type AuditConfigReference = { file: string } | null;
167
+
111
168
  export type AuditScaleSource = "default" | "explicit" | "fallback" | "scanned-css" | "token-package" | "token-sources";
112
169
 
113
170
  export type AuditDecisionKind = "adopt" | "allow" | "snap" | "undecided";
@@ -160,8 +217,11 @@ export interface AuditReport {
160
217
  decisionPlan?: AuditDecisionPlanEntry[];
161
218
  baseline?: AuditBaselineComparison | null;
162
219
  scale?: AuditScale | null;
163
- config?: string | null;
220
+ config: AuditConfigReference;
221
+ cssFilesScanned: number;
164
222
  directory: string;
223
+ /** Audited files with at least one finding. */
224
+ filesWithIssues: number;
165
225
  findings: {
166
226
  css: AuditFinding[];
167
227
  motion: AuditFinding[];
@@ -173,15 +233,34 @@ export interface AuditReport {
173
233
  offScaleProperties?: Record<string, number>;
174
234
  /** Off-scale CSS findings counted by value, top ten. */
175
235
  offScaleValues?: Record<string, number>;
236
+ /** The report format version; it changes when the report shape does. */
237
+ formatVersion: number;
238
+ motion: { enabled: boolean; findings: number; values: Record<string, number> };
239
+ /** Share of audited files with no finding, rounded down. Same as `summary.scaleCleanliness`. */
240
+ scaleCleanliness: number;
241
+ scanScope: AuditScanScope;
176
242
  scanned: AuditScanned;
177
243
  summary: AuditSummary;
244
+ /** Off-scale arbitrary values in class strings counted by value, top ten. */
245
+ tailwindArbitraryValues: Record<string, number>;
246
+ templateFilesScanned: number;
247
+ /** Defined, used, unused, missing and conflicting tokens, token chains and ladders. */
248
+ tokenContract: Record<string, unknown>;
249
+ /** Token-opportunity findings counted by value, top ten. */
250
+ tokenOpportunities: Record<string, number>;
251
+ tokenSourceWarnings: string[];
252
+ /** Files with the most findings, most first. */
253
+ topAffectedFiles: Array<{ count: number; file: string }>;
254
+ totalFiles: number;
255
+ /** Every finding. Same as `summary.totalFindings`. */
256
+ totalWarnings: number;
178
257
  [key: string]: unknown;
179
258
  }
180
259
 
181
260
  export interface AuditContractReport {
182
261
  baseline: AuditBaselineComparison | null;
183
262
  command: {
184
- config?: string | null;
263
+ config: AuditConfigReference;
185
264
  directory: string;
186
265
  scanScope: string;
187
266
  };
@@ -225,12 +304,20 @@ export const AUDIT_JSON_SCHEMA: Readonly<Record<string, unknown>>;
225
304
 
226
305
  export function createAuditReport(options?: AuditOptions): Promise<AuditReport>;
227
306
 
228
- export function loadAuditConfig(options?: AuditOptions): Record<string, unknown>;
307
+ /** The parsed `.rhythmguardrc.json`, or null when there is none or `noConfig` is set. Throws on an invalid file. */
308
+ export function loadAuditConfig(options?: AuditOptions): {
309
+ audit: Record<string, unknown>;
310
+ decisions: unknown;
311
+ file: string;
312
+ rootDir: string;
313
+ } | null;
229
314
 
230
315
  export function parseTokenSources(options?: {
231
316
  baseFontSize?: number;
232
317
  sources?: AuditTokenSource[];
233
318
  tokenKind?: AuditTokenKind;
319
+ /** Warn about a source that parses but yields no token of `tokenKind`, as the audit does. Default false. */
320
+ warnWhenEmpty?: boolean;
234
321
  }): ParsedTokenSources;
235
322
 
236
323
  export function toAuditContractReport(report: AuditReport): AuditContractReport;
package/types/index.d.ts CHANGED
@@ -9,22 +9,37 @@ import type { StylelintRuleModule } from "./rule";
9
9
  export type {
10
10
  EslintRuleModule,
11
11
  RhythmguardEslintPlugin,
12
+ MathFunctionArgumentMap,
13
+ PropertyGroupName,
14
+ RhythmguardLengthRuleOptions,
15
+ RhythmguardMotionRuleConfig,
16
+ RhythmguardMotionRuleOptions,
17
+ RhythmguardPreferTokenOptions,
12
18
  RhythmguardPresets,
19
+ RhythmguardPropertyOptions,
13
20
  RhythmguardRuleConfig,
14
21
  RhythmguardRuleOptions,
15
22
  RhythmguardStylelintConfig,
23
+ RhythmguardStylelintRules,
24
+ RhythmguardTransformRuleOptions,
25
+ RhythmguardUseScaleOptions,
26
+ ScaleOverride,
16
27
  ScalePresetMetadata,
17
28
  ScaleSource,
18
29
  ScaleValue,
30
+ StylelintRuleConfig,
31
+ StylelintSecondaryOptions,
19
32
  } from "./shared";
20
33
  export type {
21
34
  AuditBaselineComparison,
35
+ AuditConfigReference,
22
36
  AuditContractReport,
23
37
  AuditFinding,
24
38
  AuditOptions,
25
39
  AuditReport,
26
40
  AuditScale,
27
41
  AuditScaleSource,
42
+ AuditScanScope,
28
43
  AuditScanned,
29
44
  AuditSummary,
30
45
  AuditTokenKind,
package/types/shared.d.ts CHANGED
@@ -14,56 +14,158 @@ export interface ScaleSource {
14
14
  tokenPattern?: string;
15
15
  }
16
16
 
17
- export interface RhythmguardRuleOptions {
17
+ /**
18
+ * Secondary options Stylelint itself reads on every rule, so every Rhythmguard
19
+ * rule accepts them next to its own options.
20
+ */
21
+ export interface StylelintSecondaryOptions {
22
+ /** Turn off this rule's autofix while keeping its reports. */
23
+ disableFix?: boolean;
24
+ /** Replace the rule's message: a string, or a function of the message arguments. */
25
+ message?: string | ((...args: any[]) => string);
26
+ /** Report `stylelint-disable` comments for this rule as problems. */
27
+ reportDisables?: boolean;
28
+ /** `"warning"` or `"error"` (the default), or a function of the message arguments returning one of them or null. */
29
+ severity?: "warning" | "error" | ((...args: any[]) => "warning" | "error" | null);
30
+ /** A documentation link Stylelint shows with the rule's findings. */
31
+ url?: string;
32
+ }
33
+
34
+ export type PropertyGroupName = "spacing" | "radius" | "size" | "typography" | "motion";
35
+
36
+ export type MathFunctionName = "calc" | "clamp" | "min" | "max";
37
+
38
+ /** 1-based argument indexes per math function. */
39
+ export type MathFunctionArgumentMap = Partial<Record<MathFunctionName, number[]>>;
40
+
41
+ /** A scale for one property or group: values, a preset name, or a preset and/or explicit values. */
42
+ export type ScaleOverride = ScaleValue[] | string | { customScale?: ScaleValue[]; preset?: string; scale?: ScaleValue[] };
43
+
44
+ /** Options the length rules (`use-scale`, `prefer-token`, `no-offscale-transform`) share. */
45
+ export interface RhythmguardLengthRuleOptions extends StylelintSecondaryOptions {
18
46
  /** Exempt non-zero lengths of one CSS pixel or less (1px, -1px, 0.5px, 0.0625rem). Default true. */
19
47
  allowHairlines?: boolean;
48
+ /** Base for converting `rem` and `em`. Default 16. */
49
+ baseFontSize?: number;
20
50
  /** Check the static bounds of fluid values: the clamp() minimum and maximum and each length argument of min() and max(). Default false; the preferred value of clamp() is never checked. */
21
51
  checkMathBounds?: boolean;
22
- /** What autofix writes: the nearest literal (default) or, with "token", `var(--name)` when exactly one custom property holds that value in the same unit. */
23
- fixWith?: "value" | "token";
24
- /** Read the `decisions` section of `.rhythmguardrc.json` (default true). The audit sets false and applies decisions itself. */
25
- decisions?: boolean;
52
+ customScale?: ScaleValue[];
53
+ /** Lint inside `calc()`, `clamp()`, `min()` and `max()`. Default false. */
54
+ enforceInsideMathFunctions?: boolean;
55
+ /** Argument indexes skipped per math function. */
56
+ ignoreMathFunctionArguments?: MathFunctionArgumentMap;
57
+ /** Argument indexes checked per math function; the others are skipped. */
58
+ mathFunctionArguments?: MathFunctionArgumentMap;
26
59
  /** A sentence of up to 200 characters appended to every finding, after the built-in text. */
27
60
  note?: string;
28
- baseFontSize?: number;
29
- customScale?: ScaleValue[];
30
- includeMathFunctions?: boolean;
31
61
  preset?: string;
32
- properties?: Array<string | RegExp>;
33
62
  /**
34
63
  * Allowed values, or `"auto"` to infer the scale from spacing tokens: `scaleSources`,
35
64
  * then `.rhythmguardrc.json` audit token sources, then the linted stylesheet's custom
36
65
  * properties, then `tailwindConfigPath`, falling back to the `rhythmic-4` preset.
37
66
  */
38
67
  scale?: ScaleValue[] | "auto";
68
+ /** Token files consulted first when `scale` is `"auto"`. */
69
+ scaleSources?: Array<string | ScaleSource>;
70
+ /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */
71
+ tailwindConfigPath?: string;
72
+ /** Functions whose values count as tokenized. Default `["var", "theme", "token"]`. */
73
+ tokenFunctions?: string[];
74
+ /** Custom property names that count as spacing tokens. Default `"^--space-"`. */
75
+ tokenPattern?: string;
76
+ /** `"convert"` (default) compares through px; `"exact"` compares against scale values in the same unit. */
77
+ unitStrategy?: "convert" | "exact";
78
+ /** Units checked. Default `["px", "rem", "em"]`. */
79
+ units?: string[];
80
+ }
81
+
82
+ /** Options for `rhythmguard/no-offscale-transform`. */
83
+ export interface RhythmguardTransformRuleOptions extends RhythmguardLengthRuleOptions {
84
+ /** Allow negative values. Default true. */
85
+ allowNegative?: boolean;
86
+ /** Skip `%` values. Default true. */
87
+ allowPercentages?: boolean;
88
+ /** Read the `decisions` section of `.rhythmguardrc.json` (default true). The audit sets false and applies decisions itself. */
89
+ decisions?: boolean;
90
+ /** Autofix to the nearest scale value. Default true. */
91
+ fixToScale?: boolean;
92
+ /** What autofix writes: the nearest literal (default) or, with "token", `var(--name)` when exactly one custom property holds that value in the same unit. */
93
+ fixWith?: "value" | "token";
94
+ }
95
+
96
+ /** Property selection, shared by `use-scale` and `prefer-token`. */
97
+ export interface RhythmguardPropertyOptions {
98
+ /** Keyword literals to skip. Default the CSS global keywords and `auto`. */
99
+ ignoreValues?: string[];
100
+ /** Properties checked: names, `/regex/flags` strings or RegExps. Overrides `propertyGroups`. */
101
+ properties?: Array<string | RegExp>;
102
+ /** Built-in property groups, used when `properties` is not set. Default `["spacing"]`. */
103
+ propertyGroups?: PropertyGroupName[];
104
+ /** A scale per property name or `/regex/flags` key, used before `scales` and `scale`. */
105
+ propertyScales?: Record<string, ScaleOverride>;
39
106
  /**
40
107
  * A scale per property group, used before `scale` and after `propertyScales`: values, a
41
108
  * preset name, or `"auto"` to infer the group's scale from its tokens (`--font-size-*` and
42
109
  * `--text-*` for typography, `--radius-*` for radius). Findings then name the group's scale.
43
110
  */
44
- scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", ScaleValue[] | string | { preset?: string; scale?: ScaleValue[]; customScale?: ScaleValue[] }>>;
45
- /** Token files consulted first when `scale` is `"auto"`. */
46
- scaleSources?: Array<string | ScaleSource>;
47
- /** Tailwind v3 config whose `theme.spacing` feeds `scale: "auto"` and `tokenMapFromTailwindSpacing`. */
48
- tailwindConfigPath?: string;
111
+ scales?: Partial<Record<"spacing" | "radius" | "size" | "typography", ScaleOverride | "auto">>;
112
+ }
113
+
114
+ /** Options for `rhythmguard/use-scale`. */
115
+ export interface RhythmguardUseScaleOptions extends RhythmguardTransformRuleOptions, RhythmguardPropertyOptions {}
116
+
117
+ /** Options for `rhythmguard/prefer-token`. */
118
+ export interface RhythmguardPreferTokenOptions extends RhythmguardLengthRuleOptions, RhythmguardPropertyOptions {
119
+ /** Migration mode: on-scale literals pass. Default false. */
120
+ allowNumericScale?: boolean;
121
+ /** Raw value to token replacements, such as `{ "16px": "var(--space-4)" }`. */
49
122
  tokenMap?: Record<string, string>;
50
123
  tokenMapFile?: string;
51
124
  tokenMapFromCssCustomProperties?: boolean;
52
125
  tokenMapFromTailwindSpacing?: boolean;
53
- tokenPattern?: string;
54
126
  }
55
127
 
56
- export type RhythmguardRuleConfig =
128
+ /** Every option a length rule accepts; each rule rejects the ones that are not its own. */
129
+ export interface RhythmguardRuleOptions extends RhythmguardUseScaleOptions, RhythmguardPreferTokenOptions {}
130
+
131
+ /** Options for `rhythmguard/use-motion-scale`. */
132
+ export interface RhythmguardMotionRuleOptions extends StylelintSecondaryOptions {
133
+ /** Allowed duration and delay values in milliseconds. Default `[0, 75, 100, 150, 200, 300, 500, 700, 1000]`. */
134
+ durationScale?: number[];
135
+ /** Time units checked. Default `["ms", "s"]`. */
136
+ durationUnits?: Array<"ms" | "s">;
137
+ /** Exact replacements for raw easing functions. */
138
+ easingTokenMap?: Record<string, string>;
139
+ /** Autofix simple durations and delays to the nearest scale value. Default true. */
140
+ fixToScale?: boolean;
141
+ /** A sentence of up to 200 characters appended to every finding, after the built-in text. */
142
+ note?: string;
143
+ }
144
+
145
+ export type StylelintRuleConfig<Options> =
57
146
  | null
58
147
  | RuleSeverity
59
- | [RuleSeverity, RhythmguardRuleOptions];
148
+ | [RuleSeverity]
149
+ | [RuleSeverity, Options];
150
+
151
+ export type RhythmguardRuleConfig = StylelintRuleConfig<RhythmguardRuleOptions>;
152
+
153
+ export type RhythmguardMotionRuleConfig = StylelintRuleConfig<RhythmguardMotionRuleOptions>;
154
+
155
+ export interface RhythmguardStylelintRules {
156
+ "rhythmguard/no-offscale-transform"?: StylelintRuleConfig<RhythmguardTransformRuleOptions>;
157
+ "rhythmguard/prefer-token"?: StylelintRuleConfig<RhythmguardPreferTokenOptions>;
158
+ "rhythmguard/use-motion-scale"?: RhythmguardMotionRuleConfig;
159
+ "rhythmguard/use-scale"?: StylelintRuleConfig<RhythmguardUseScaleOptions>;
160
+ [ruleName: string]: RhythmguardRuleConfig | RhythmguardMotionRuleConfig | undefined;
161
+ }
60
162
 
61
163
  export interface RhythmguardStylelintConfig {
62
164
  customSyntax?: string;
63
165
  extends?: string | string[];
64
166
  ignoreFiles?: string | string[];
65
167
  plugins?: string[];
66
- rules?: Record<string, RhythmguardRuleConfig>;
168
+ rules?: RhythmguardStylelintRules;
67
169
  }
68
170
 
69
171
  export interface ScalePresetMetadata {
@@ -77,8 +179,10 @@ export interface ScalePresetMetadata {
77
179
 
78
180
  export interface RhythmguardPresets {
79
181
  communityScaleMetadata: Record<string, ScalePresetMetadata>;
80
- getCommunityScaleMetadata(name: string): ScalePresetMetadata | undefined;
81
- getScalePreset(name: string): readonly number[] | undefined;
182
+ /** The metadata of a community scale, or null for an unknown name. */
183
+ getCommunityScaleMetadata(name: string): ScalePresetMetadata | null;
184
+ /** A preset's values, or null for an unknown name. */
185
+ getScalePreset(name: string): readonly number[] | null;
82
186
  listCommunityScalePresetNames(): string[];
83
187
  listScalePresetNames(): string[];
84
188
  scales: Record<string, readonly number[]>;
@@ -109,7 +213,9 @@ export interface EslintRuleModule {
109
213
 
110
214
  export interface RhythmguardEslintPlugin {
111
215
  configs: {
216
+ /** A flat config that registers the plugin itself, so it can stand alone in a config array. */
112
217
  recommended: {
218
+ plugins: { "rhythmguard-tailwind": RhythmguardEslintPlugin };
113
219
  rules: Record<string, EslintRuleSeverity>;
114
220
  };
115
221
  };