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.
- package/CHANGELOG.md +57 -0
- package/README.md +1 -1
- package/package.json +23 -1
- package/src/audit/args.js +23 -4
- package/src/audit/baseline.js +15 -2
- package/src/audit/codemod.js +56 -5
- package/src/audit/config.js +2 -1
- package/src/audit/contract.js +3 -0
- package/src/audit/decisions.js +45 -16
- package/src/audit/render-markdown.js +22 -21
- package/src/audit/render-text.js +4 -0
- package/src/audit/render-utils.js +28 -1
- package/src/audit/report.js +16 -2
- package/src/audit/scan/files.js +139 -30
- package/src/audit/token-chains.js +4 -1
- package/src/audit/token-ladders.js +23 -2
- package/src/cli/doctor.js +58 -6
- package/src/cli/fix.js +7 -6
- package/src/cli/index.js +2 -2
- package/src/cli/init.js +41 -5
- package/src/cli/quickstart.js +46 -8
- package/src/configs/embed.js +2 -0
- package/src/configs/motion.js +1 -0
- package/src/configs/recommended.js +1 -0
- package/src/configs/strict.js +1 -0
- package/src/configs/tailwind.js +1 -0
- package/src/core/decisions.js +2 -1
- package/src/core/json.js +25 -0
- package/src/core/length.js +11 -0
- package/src/core/options.js +39 -20
- package/src/core/scale-inference.js +78 -23
- package/src/core/tailwind-class-analysis.js +3 -2
- package/src/core/token-map.js +2 -1
- package/src/core/token-sources.js +143 -14
- package/src/eslint/index.js +14 -8
- package/src/eslint/rules/tailwind-class-use-motion-scale.js +1 -0
- package/src/eslint/rules/tailwind-class-use-scale.js +1 -0
- package/src/rules/no-offscale-transform/index.js +58 -53
- package/src/rules/prefer-token/index.js +31 -46
- package/src/rules/use-motion-scale/index.js +14 -1
- package/src/rules/use-scale/index.js +75 -102
- package/src/rules/validate.js +13 -4
- package/types/__checks__/consumer.ts +20 -1
- package/types/__checks__/eslint-config.ts +8 -0
- package/types/__checks__/shipped-configs.ts +96 -0
- package/types/audit.d.ts +103 -16
- package/types/index.d.ts +15 -0
- 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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
|
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
|
|
68
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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",
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
|
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?:
|
|
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
|
-
|
|
81
|
-
|
|
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
|
};
|