@better-css-modules/core 0.1.3 → 0.2.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.
@@ -0,0 +1,275 @@
1
+ import "postcss";
2
+ //#region src/config.d.ts
3
+ /** The config as written in `better-css-modules.config.*`; every key is optional. */
4
+ interface Config {
5
+ /** Glob patterns for target files */
6
+ include?: string[];
7
+ /** Exclusion patterns */
8
+ exclude?: string[];
9
+ /** Output directory, inside the project root */
10
+ outDir?: string;
11
+ /** Leave out the progress lines; diagnostics and errors are always printed */
12
+ silent?: boolean;
13
+ /**
14
+ * Declare the classes as named exports instead of a default export, as
15
+ * webpack's css-loader and Rspack's built-in CSS export them by default.
16
+ */
17
+ namedExports?: boolean;
18
+ /**
19
+ * Global stylesheets that declare the design tokens, in cascade order:
20
+ * `./` or `../` paths relative to the config, or package specifiers.
21
+ */
22
+ globalCss?: string[];
23
+ /** Cascade layer the bundler plugins wrap every CSS Modules file in; unset leaves files as written */
24
+ layer?: string;
25
+ }
26
+ /** The config with its defaults filled in, checked, and tied to the project root. */
27
+ interface ResolvedConfig {
28
+ /** The directory every relative path is resolved against: the config file's, or the cwd without one. */
29
+ root: string;
30
+ /** Absolute path of the config file, or null without one. */
31
+ file: string | null;
32
+ include: string[];
33
+ exclude: string[];
34
+ /** Relative to `root`, with `/` separators; `"."` puts each `.d.ts` next to its stylesheet. */
35
+ outDir: string;
36
+ silent: boolean;
37
+ namedExports: boolean;
38
+ globalCss: string[];
39
+ layer?: string;
40
+ }
41
+ /** A mistake in the config or the files it names, which stops generating or checking. */
42
+ declare class ConfigError extends Error {
43
+ name: string;
44
+ }
45
+ declare function defineConfig(config: Config): Config;
46
+ /**
47
+ * Load the config file `config` names, or the one in `cwd` when it names none,
48
+ * and resolve it. Without a config file the defaults apply, rooted at `cwd`.
49
+ */
50
+ declare function loadConfig({ cwd, config }?: {
51
+ cwd?: string;
52
+ config?: string;
53
+ }): Promise<ResolvedConfig>;
54
+ //#endregion
55
+ //#region src/tokens.d.ts
56
+ /**
57
+ * The categories of design tokens. A custom property belongs to a category by
58
+ * its name: `--<category>` itself or `--<category>-*`. This table is the single
59
+ * definition of what each category covers; the README lists it for users.
60
+ */
61
+ declare const tokenCategories: {
62
+ color: {
63
+ properties: {
64
+ color: "colors";
65
+ "background-color": "colors";
66
+ "outline-color": "colors";
67
+ "text-decoration-color": "colors";
68
+ "text-emphasis-color": "colors";
69
+ "column-rule-color": "colors";
70
+ "caret-color": "colors";
71
+ "accent-color": "colors";
72
+ "scrollbar-color": "colors";
73
+ fill: "colors";
74
+ stroke: "colors";
75
+ "stop-color": "colors";
76
+ "flood-color": "colors";
77
+ "lighting-color": "colors";
78
+ "-webkit-text-fill-color": "colors";
79
+ "-webkit-text-stroke-color": "colors";
80
+ "-webkit-tap-highlight-color": "colors";
81
+ background: "layer-color";
82
+ outline: "layer-color";
83
+ "text-decoration": "layer-color";
84
+ "text-emphasis": "layer-color";
85
+ "column-rule": "layer-color";
86
+ "-webkit-text-stroke": "layer-color";
87
+ "box-shadow": "shadow-color";
88
+ "text-shadow": "shadow-color";
89
+ "background-image": "gradient-colors";
90
+ "border-image": "gradient-colors";
91
+ "border-image-source": "gradient-colors";
92
+ };
93
+ keywords: string[];
94
+ };
95
+ spacing: {
96
+ properties: {
97
+ inset: "value";
98
+ top: "value";
99
+ right: "value";
100
+ bottom: "value";
101
+ left: "value";
102
+ "inset-block": "value";
103
+ "inset-block-start": "value";
104
+ "inset-block-end": "value";
105
+ "inset-inline": "value";
106
+ "inset-inline-start": "value";
107
+ "inset-inline-end": "value";
108
+ gap: "value";
109
+ "row-gap": "value";
110
+ "column-gap": "value";
111
+ };
112
+ keywords: string[];
113
+ percentages: true;
114
+ };
115
+ radius: {
116
+ properties: {
117
+ "border-radius": "value";
118
+ "border-top-left-radius": "value";
119
+ "border-top-right-radius": "value";
120
+ "border-bottom-right-radius": "value";
121
+ "border-bottom-left-radius": "value";
122
+ "border-start-start-radius": "value";
123
+ "border-start-end-radius": "value";
124
+ "border-end-start-radius": "value";
125
+ "border-end-end-radius": "value";
126
+ };
127
+ keywords: never[];
128
+ percentages: true;
129
+ };
130
+ shadow: {
131
+ properties: {
132
+ "box-shadow": "shadows";
133
+ "text-shadow": "shadows";
134
+ };
135
+ keywords: string[];
136
+ };
137
+ "font-size": {
138
+ properties: {
139
+ "font-size": "value";
140
+ font: "font";
141
+ };
142
+ keywords: never[];
143
+ };
144
+ "font-weight": {
145
+ properties: {
146
+ "font-weight": "value";
147
+ font: "font";
148
+ };
149
+ keywords: string[];
150
+ };
151
+ "line-height": {
152
+ properties: {
153
+ "line-height": "value";
154
+ font: "font";
155
+ };
156
+ keywords: string[];
157
+ };
158
+ "z-index": {
159
+ properties: {
160
+ "z-index": "value";
161
+ };
162
+ keywords: string[];
163
+ };
164
+ duration: {
165
+ properties: {
166
+ "transition-duration": "value";
167
+ "transition-delay": "value";
168
+ "animation-duration": "value";
169
+ "animation-delay": "value";
170
+ transition: "times";
171
+ animation: "times";
172
+ };
173
+ keywords: string[];
174
+ };
175
+ breakpoint: {
176
+ properties: {};
177
+ keywords: never[];
178
+ };
179
+ };
180
+ type TokenCategory = keyof typeof tokenCategories;
181
+ //#endregion
182
+ //#region src/rules.d.ts
183
+ /** Every rule but the token categories, with how it can be disabled. */
184
+ declare const RULES: {
185
+ readonly "usage/unused-class": "either";
186
+ readonly "usage/unused-module": "file-wide";
187
+ readonly "usage/unanalyzable": "file-wide";
188
+ readonly "pure/selector": "either";
189
+ readonly "pure/subject": "either";
190
+ readonly "pure/global": "either";
191
+ readonly "pure/id": "either";
192
+ readonly "pure/important": "either";
193
+ readonly "pure/at-rule": "either";
194
+ readonly "pure/value": "either";
195
+ readonly "tokens/unknown": "either";
196
+ readonly "tokens/internal": "either";
197
+ readonly "tokens/declaration": "either";
198
+ readonly "layer/nested": "either";
199
+ readonly "layer/composes": {
200
+ readonly never: "the plugins stop the build at composes in a layer";
201
+ };
202
+ readonly syntax: {
203
+ readonly never: "the bundlers cannot read the stylesheet either";
204
+ };
205
+ readonly "invalid-composes": {
206
+ readonly never: "the bundlers reject composes there";
207
+ };
208
+ readonly "invalid-disable": {
209
+ readonly never: "fix or remove the disable comment instead";
210
+ };
211
+ };
212
+ /** The identifier of a rule, which diagnostics carry and disable comments name. */
213
+ type RuleId = keyof typeof RULES | `tokens/${TokenCategory}`;
214
+ //#endregion
215
+ //#region src/diagnostic.d.ts
216
+ interface Diagnostic {
217
+ /** Absolute path of the file the diagnostic points at. */
218
+ file: string;
219
+ /** 1-based line. */
220
+ line: number;
221
+ /** 1-based column. */
222
+ column: number;
223
+ /** 1-based line of the end of the range. */
224
+ endLine?: number;
225
+ /** 1-based column just after the last character of the range, as in SARIF. */
226
+ endColumn?: number;
227
+ rule: RuleId;
228
+ message: string;
229
+ }
230
+ /** `path:line:col error rule: message`, with the path relative to `cwd`. */
231
+ declare function formatDiagnostic(diagnostic: Diagnostic, cwd: string): string;
232
+ /** GitHub Actions workflow command that annotates the file in a pull request. */
233
+ declare function formatGitHubAnnotation(diagnostic: Diagnostic, cwd: string): string;
234
+ //#endregion
235
+ //#region src/project.d.ts
236
+ /** What telling the included CSS Modules files apart reads of the config. */
237
+ type ModuleOptions = Pick<ResolvedConfig, "root" | "include" | "exclude" | "outDir">;
238
+ //#endregion
239
+ //#region src/layer.d.ts
240
+ interface WrapResult {
241
+ code: string;
242
+ /** Source map, as JSON. */
243
+ map: string;
244
+ }
245
+ /** What wrapping modules in the layer reads of the config. */
246
+ type LayerConfig = ModuleOptions & Pick<ResolvedConfig, "globalCss" | "layer">;
247
+ /**
248
+ * What the bundler plugins run on each stylesheet: it wraps the CSS Modules
249
+ * files the config includes in the layer it names, and resolves to null for
250
+ * any other file, or for every file when the config names no layer.
251
+ *
252
+ * `depend` receives each file of the global CSS it read, also when reading
253
+ * one failed, before the layer is resolved, so that the bundler wraps the
254
+ * module again once the file is fixed or the layer declared. The global CSS
255
+ * is read again only after one of its files has changed, and a read that
256
+ * failed is tried again on the next call.
257
+ */
258
+ declare function createLayerWrapper(config: LayerConfig): (source: string, file: string, depend: (file: string) => void) => Promise<WrapResult | null>;
259
+ //#endregion
260
+ //#region src/dts.d.ts
261
+ interface GenerateResult {
262
+ /** Paths of the `.d.ts` files, written or already up to date. */
263
+ files: string[];
264
+ /** Paths of the `.d.ts` files removed because no included stylesheet produces them any more. */
265
+ removed: string[];
266
+ /** The syntax problems of the stylesheets, sorted. */
267
+ diagnostics: Diagnostic[];
268
+ }
269
+ /**
270
+ * Generate `.d.ts` files for every CSS Modules file the config includes, and
271
+ * remove the ones it wrote for stylesheets it no longer includes.
272
+ */
273
+ declare function generate(config: ResolvedConfig): Promise<GenerateResult>;
274
+ //#endregion
275
+ export { Diagnostic as a, RuleId as c, ConfigError as d, ResolvedConfig as f, createLayerWrapper as i, TokenCategory as l, loadConfig as m, generate as n, formatDiagnostic as o, defineConfig as p, LayerConfig as r, formatGitHubAnnotation as s, GenerateResult as t, Config as u };
package/dist/index.d.mts CHANGED
@@ -1,62 +1,20 @@
1
- import * as chokidar from "chokidar";
2
-
3
- //#region src/config.d.ts
4
- interface Config {
5
- /** Glob patterns for target files */
6
- include: string[];
7
- /** Exclusion patterns */
8
- exclude: string[];
9
- /** Output directory */
10
- outDir: string;
11
- /** Watch mode (for CLI) */
12
- watch: boolean;
13
- /** Suppress console output */
14
- silent: boolean;
1
+ import { a as Diagnostic, c as RuleId, d as ConfigError, f as ResolvedConfig, l as TokenCategory, m as loadConfig, n as generate, o as formatDiagnostic, p as defineConfig, s as formatGitHubAnnotation, t as GenerateResult, u as Config } from "./dts-BjIczsCF.mjs";
2
+ import "postcss";
3
+ //#region src/check.d.ts
4
+ interface CheckResult {
5
+ /** The problems found, sorted. */
6
+ diagnostics: Diagnostic[];
7
+ /** How many CSS Modules files were checked. */
8
+ modules: number;
9
+ /** The token categories the global CSS declares, which are restricted. */
10
+ tokens: TokenCategory[];
15
11
  }
16
- declare function defineConfig(config: Partial<Config>): Config;
17
- declare function loadConfig(cwd?: string): Promise<Config>;
18
- //#endregion
19
- //#region src/parser.d.ts
20
- /**
21
- * Extract class names from CSS file contents.
22
- */
23
- declare function extractClassNames(css: string): string[];
24
- /**
25
- * Read a CSS Modules file and extract class names.
26
- */
27
- declare function parseFile(filePath: string): Promise<string[]>;
28
- //#endregion
29
- //#region src/generator.d.ts
30
- /**
31
- * Generate .d.ts content from an array of class names.
32
- */
33
- declare function generateDts(classNames: string[]): string;
34
12
  /**
35
- * Generate and write a .d.ts file for a CSS Modules file.
36
- *
37
- * @param cssFilePath - Path to the source CSS Modules file
38
- * @param classNames - Array of extracted class names
39
- * @param outDir - Output directory
40
- * @param cwd - Working directory
13
+ * Check the project: every CSS Modules file the config includes, how the
14
+ * sources use them, and the project's own global CSS. Throws ConfigError when
15
+ * include matches no file, the global CSS cannot be read, or it does not
16
+ * declare the layer.
41
17
  */
42
- declare function writeDts(cssFilePath: string, classNames: string[], outDir: string, cwd?: string): Promise<string>;
43
- /**
44
- * Batch-generate .d.ts files for all CSS Modules files based on the config.
45
- */
46
- declare function generateAll(config: Config, cwd?: string): Promise<string[]>;
47
- //#endregion
48
- //#region src/scanner.d.ts
49
- interface UnusedClassWarning {
50
- cssFile: string;
51
- className: string;
52
- }
53
- /**
54
- * Scan TS/TSX files under the specified directory
55
- * and detect unused CSS Modules class names.
56
- */
57
- declare function scanUnusedClasses(cwd: string): Promise<UnusedClassWarning[]>;
58
- //#endregion
59
- //#region src/watcher.d.ts
60
- declare function startWatcher(config: Config, cwd?: string): chokidar.FSWatcher;
18
+ export declare function check(config: ResolvedConfig): Promise<CheckResult>;
61
19
  //#endregion
62
- export { type Config, type UnusedClassWarning, defineConfig, extractClassNames, generateAll, generateDts, loadConfig, parseFile, scanUnusedClasses, startWatcher, writeDts };
20
+ export { type CheckResult, type Config, ConfigError, type Diagnostic, type GenerateResult, type ResolvedConfig, type RuleId, defineConfig, formatDiagnostic, formatGitHubAnnotation, generate, loadConfig };