@marktiderman/genesis-cli 1.1.1 → 1.3.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/README.md +189 -4
- package/dist/cli.js +1286 -26
- package/dist/cli.js.map +1 -1
- package/dist/doctor.d.ts +232 -0
- package/dist/doctor.js +1021 -0
- package/dist/doctor.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1004 -9
- package/dist/index.js.map +1 -1
- package/dist/vite.d.ts +15 -0
- package/dist/vite.js +1092 -0
- package/dist/vite.js.map +1 -0
- package/package.json +22 -3
package/dist/doctor.d.ts
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public types for `genesis doctor` and its rule plugins.
|
|
3
|
+
*/
|
|
4
|
+
type Level = "error" | "warn";
|
|
5
|
+
/** A rule's configured level: a level, or `"off"` to drop its findings. */
|
|
6
|
+
type RuleSetting = Level | "off";
|
|
7
|
+
/** One problem the doctor found. */
|
|
8
|
+
interface Finding {
|
|
9
|
+
/** The rule that produced it, e.g. `raw-tag` or a pattern/plugin rule id. */
|
|
10
|
+
rule: string;
|
|
11
|
+
level: Level;
|
|
12
|
+
/** Path relative to the app root, POSIX separators. */
|
|
13
|
+
file: string;
|
|
14
|
+
/** 1-based line, or 0 when the finding is about the whole file. */
|
|
15
|
+
line: number;
|
|
16
|
+
message: string;
|
|
17
|
+
/**
|
|
18
|
+
* What the finding is about (a tag, token, export name, import specifier).
|
|
19
|
+
* An `allow` entry's `match` is compared against it.
|
|
20
|
+
*/
|
|
21
|
+
subject?: string;
|
|
22
|
+
}
|
|
23
|
+
/** What a rule or plugin passes to `report`. `level` defaults to `"error"`. */
|
|
24
|
+
interface FindingInput {
|
|
25
|
+
rule: string;
|
|
26
|
+
level?: Level;
|
|
27
|
+
file: string;
|
|
28
|
+
line?: number;
|
|
29
|
+
message: string;
|
|
30
|
+
subject?: string;
|
|
31
|
+
}
|
|
32
|
+
/** A justified exception. `reason` is required: an exception nobody can explain is a bug. */
|
|
33
|
+
interface AllowEntry {
|
|
34
|
+
rule: string;
|
|
35
|
+
/** Glob relative to the app root. Omit to allow in every file. */
|
|
36
|
+
file?: string;
|
|
37
|
+
/** Exact subject (tag, token, export name, import specifier). Omit to allow any. */
|
|
38
|
+
match?: string;
|
|
39
|
+
reason: string;
|
|
40
|
+
}
|
|
41
|
+
/** A declarative check: which files it covers and the pattern they must (not) contain. */
|
|
42
|
+
interface PatternRule {
|
|
43
|
+
id: string;
|
|
44
|
+
/** `guide` documents a convention and is never checked. Default `error`. */
|
|
45
|
+
level?: Level | "guide";
|
|
46
|
+
/** Globs the rule applies to. Required unless the level is `guide`. */
|
|
47
|
+
files?: string[];
|
|
48
|
+
exclude?: string[];
|
|
49
|
+
/** Regular expression that must not appear (multiline). Prefix `(?i)` for case-insensitive. */
|
|
50
|
+
forbid?: string;
|
|
51
|
+
/** Regular expression every matching file must contain. */
|
|
52
|
+
require?: string;
|
|
53
|
+
/** Regular expression every matching file's path must fit. */
|
|
54
|
+
path?: string;
|
|
55
|
+
message?: string;
|
|
56
|
+
}
|
|
57
|
+
/** A plugin entry in config: a module path, or `[path, options]`. */
|
|
58
|
+
type PluginSpec = string | [string, unknown];
|
|
59
|
+
/** The `doctor` block of genesis.config.json (or package.json `genesis.doctor`). */
|
|
60
|
+
interface DoctorConfig {
|
|
61
|
+
/** Folders to scan, relative to the app root. Default `["src"]`. */
|
|
62
|
+
src?: string[];
|
|
63
|
+
/** File extensions to scan. Default `.ts .tsx .js .jsx .mts .cts .css`. */
|
|
64
|
+
extensions?: string[];
|
|
65
|
+
/** Extra globs to skip, on top of the defaults (tests, fixtures, `.d.ts`, `*.gen.*`). */
|
|
66
|
+
ignore?: string[];
|
|
67
|
+
/** The component package. Default `@marktiderman/genesis-ui`. */
|
|
68
|
+
uiPackage?: string;
|
|
69
|
+
/**
|
|
70
|
+
* Theme stylesheet(s) whose custom properties are the defined tokens: one
|
|
71
|
+
* or a list of package specifiers (`@scope/pkg/path.css`) or app-relative
|
|
72
|
+
* paths. Default: every `.css` in the design system's `dist/themes/`
|
|
73
|
+
* (genesis.css and the Tailwind v4 bridge genesis-tailwind4.css), plus
|
|
74
|
+
* genesis-ui's styles.
|
|
75
|
+
*/
|
|
76
|
+
themeCss?: string | string[];
|
|
77
|
+
/**
|
|
78
|
+
* App files whose custom-property declarations also count as defined
|
|
79
|
+
* tokens (a brand bridge). Default: every scanned `.css` file.
|
|
80
|
+
*/
|
|
81
|
+
tokenFiles?: string[];
|
|
82
|
+
/** Token prefixes never reported as undefined. Default `--tw-`, `--radix-`. */
|
|
83
|
+
ignoreTokenPrefixes?: string[];
|
|
84
|
+
/** Extra raw-tag → component mappings (`{ "img": "Avatar" }`), or `false` to stop checking a tag. */
|
|
85
|
+
rawTags?: Record<string, string | false>;
|
|
86
|
+
/** Extra import specifiers to forbid: regular expression → message. Added to the defaults. */
|
|
87
|
+
forbiddenImports?: Record<string, string>;
|
|
88
|
+
/** Folders that must not exist (local design-system primitives). Default `["src/components/ui"]`. */
|
|
89
|
+
localPrimitiveDirs?: string[];
|
|
90
|
+
/** Per-rule level overrides, e.g. `{ "raw-color": "warn", "palette-color": "off" }`. */
|
|
91
|
+
rules?: Record<string, RuleSetting>;
|
|
92
|
+
/** Justified exceptions. */
|
|
93
|
+
allow?: AllowEntry[];
|
|
94
|
+
/** Declarative app rules. */
|
|
95
|
+
patterns?: PatternRule[];
|
|
96
|
+
/** A markdown file of pattern rules (`### rule-id` blocks of `- key: value` lines). */
|
|
97
|
+
rulesDoc?: string;
|
|
98
|
+
/** Rule modules, resolved relative to the config file. */
|
|
99
|
+
plugins?: PluginSpec[];
|
|
100
|
+
/** Commands `--build` runs, in order. Default: the app's `typecheck` then `build` scripts. */
|
|
101
|
+
build?: string[];
|
|
102
|
+
}
|
|
103
|
+
/** Facts read from the installed Genesis packages. Nothing here is hardcoded. */
|
|
104
|
+
interface GenesisFacts {
|
|
105
|
+
uiPackage: string;
|
|
106
|
+
uiVersion: string;
|
|
107
|
+
/** Every name exported from the component package (all subpaths). */
|
|
108
|
+
exports: ReadonlySet<string>;
|
|
109
|
+
/** Exported values (not types): what an app could shadow. */
|
|
110
|
+
values: ReadonlySet<string>;
|
|
111
|
+
/** Exported components, sorted. */
|
|
112
|
+
components: readonly string[];
|
|
113
|
+
/** Custom properties the theme stylesheets define. */
|
|
114
|
+
tokens: ReadonlySet<string>;
|
|
115
|
+
/** Raw HTML tag → the Genesis component that replaces it. */
|
|
116
|
+
rawTags: ReadonlyMap<string, string>;
|
|
117
|
+
/** Tailwind palette color names (red, slate, …). */
|
|
118
|
+
palette: readonly string[];
|
|
119
|
+
}
|
|
120
|
+
/** One scanned file. */
|
|
121
|
+
interface SourceFile {
|
|
122
|
+
/** Path relative to the app root, POSIX separators. */
|
|
123
|
+
path: string;
|
|
124
|
+
absolutePath: string;
|
|
125
|
+
/** Extension including the dot, e.g. `.tsx`. */
|
|
126
|
+
ext: string;
|
|
127
|
+
/** Raw contents. */
|
|
128
|
+
text: string;
|
|
129
|
+
/** Contents with comments blanked out (line numbers preserved). */
|
|
130
|
+
code: string;
|
|
131
|
+
}
|
|
132
|
+
/** What a plugin's `check` receives. */
|
|
133
|
+
interface DoctorContext {
|
|
134
|
+
root: string;
|
|
135
|
+
files: readonly SourceFile[];
|
|
136
|
+
genesis: GenesisFacts;
|
|
137
|
+
config: DoctorConfig;
|
|
138
|
+
/** Record a finding. Config `rules` levels and `allow` entries apply afterwards. */
|
|
139
|
+
report(finding: FindingInput): void;
|
|
140
|
+
}
|
|
141
|
+
/** A rule module. Default-export one, an array, or a factory that takes the config options. */
|
|
142
|
+
interface DoctorPlugin {
|
|
143
|
+
name: string;
|
|
144
|
+
check(context: DoctorContext): void | Promise<void>;
|
|
145
|
+
}
|
|
146
|
+
interface DoctorResult {
|
|
147
|
+
ok: boolean;
|
|
148
|
+
root: string;
|
|
149
|
+
genesis: GenesisFacts;
|
|
150
|
+
findings: Finding[];
|
|
151
|
+
/** Genesis components no scanned file imports. */
|
|
152
|
+
unused: string[];
|
|
153
|
+
/** Pattern rules plus plugins that ran. */
|
|
154
|
+
ruleCount: number;
|
|
155
|
+
errors: number;
|
|
156
|
+
warnings: number;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
declare class DoctorConfigError extends Error {
|
|
160
|
+
name: string;
|
|
161
|
+
}
|
|
162
|
+
interface LoadedConfig {
|
|
163
|
+
config: DoctorConfig;
|
|
164
|
+
/** The file it came from, or null when no config exists (defaults apply). */
|
|
165
|
+
file: string | null;
|
|
166
|
+
/** Folder that relative plugin paths resolve against. */
|
|
167
|
+
dir: string;
|
|
168
|
+
}
|
|
169
|
+
declare function loadConfig(root: string, configPath?: string): LoadedConfig;
|
|
170
|
+
/** Check the shape, so a typo fails loudly instead of silently disabling a check. */
|
|
171
|
+
declare function validateConfig(raw: unknown, source?: string): DoctorConfig;
|
|
172
|
+
|
|
173
|
+
/** The installed folder of `name`, looking in node_modules from `from` upward (works with hoisting and pnpm). */
|
|
174
|
+
declare function findPackageDir(from: string, name: string): string | null;
|
|
175
|
+
declare function loadGenesis(root: string, config: DoctorConfig): GenesisFacts;
|
|
176
|
+
/** Names exported by a declaration file: `export { a, b as c }` blocks and `export declare …` statements. */
|
|
177
|
+
declare function parseExportNames(dts: string): string[];
|
|
178
|
+
|
|
179
|
+
declare function parseRulesMarkdown(markdown: string): PatternRule[];
|
|
180
|
+
|
|
181
|
+
/** Identity helper that types a plugin. */
|
|
182
|
+
declare function defineDoctorPlugin(plugin: DoctorPlugin): DoctorPlugin;
|
|
183
|
+
|
|
184
|
+
/** Ids of the built-in rules, for `rules` overrides and `allow` entries. */
|
|
185
|
+
declare const BUILTIN_RULES: readonly ["local-primitives", "starter-leftover", "forbidden-import", "raw-tag", "palette-color", "arbitrary-color", "raw-color", "undefined-token", "shadowed-export"];
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Minimal globs for config: `*` matches within a folder, `**` across folders,
|
|
189
|
+
* `?` one character, and a trailing `/` means "everything under this folder".
|
|
190
|
+
*/
|
|
191
|
+
declare function globToRegExp(glob: string): RegExp;
|
|
192
|
+
|
|
193
|
+
interface RunDoctorOptions {
|
|
194
|
+
/** The app root. Default `process.cwd()`. */
|
|
195
|
+
root?: string;
|
|
196
|
+
/** Explicit config file (otherwise genesis.config.json, then package.json `genesis`). */
|
|
197
|
+
configPath?: string;
|
|
198
|
+
/** Use this config instead of reading one. Relative plugin paths resolve from `root`. */
|
|
199
|
+
config?: DoctorConfig;
|
|
200
|
+
/** Treat warnings as failures. */
|
|
201
|
+
strict?: boolean;
|
|
202
|
+
/** Run the app's typecheck and build after the checks. */
|
|
203
|
+
build?: boolean;
|
|
204
|
+
/** Pipe build output instead of inheriting the terminal (for --json). */
|
|
205
|
+
quietBuild?: boolean;
|
|
206
|
+
/** Reuse facts read earlier (the Vite dev server caches them). */
|
|
207
|
+
genesis?: GenesisFacts;
|
|
208
|
+
}
|
|
209
|
+
declare function runDoctor(options?: RunDoctorOptions): Promise<DoctorResult>;
|
|
210
|
+
/** The human-readable report. */
|
|
211
|
+
declare function formatReport(result: DoctorResult): string;
|
|
212
|
+
/** The `--json` report: plain data, sets turned into sorted lists. */
|
|
213
|
+
declare function toJson(result: DoctorResult): {
|
|
214
|
+
ok: boolean;
|
|
215
|
+
genesis: string;
|
|
216
|
+
errors: number;
|
|
217
|
+
warnings: number;
|
|
218
|
+
findings: Finding[];
|
|
219
|
+
unused: string[];
|
|
220
|
+
};
|
|
221
|
+
/** What `--print-genesis` shows: the facts every rule is derived from. */
|
|
222
|
+
declare function genesisSummary(g: GenesisFacts): {
|
|
223
|
+
package: string;
|
|
224
|
+
components: readonly string[];
|
|
225
|
+
tokens: string[];
|
|
226
|
+
rawTags: {
|
|
227
|
+
[k: string]: string;
|
|
228
|
+
};
|
|
229
|
+
palette: readonly string[];
|
|
230
|
+
};
|
|
231
|
+
|
|
232
|
+
export { type AllowEntry, BUILTIN_RULES, type DoctorConfig, DoctorConfigError, type DoctorContext, type DoctorPlugin, type DoctorResult, type Finding, type FindingInput, type GenesisFacts, type Level, type PatternRule, type PluginSpec, type RuleSetting, type RunDoctorOptions, type SourceFile, defineDoctorPlugin, findPackageDir, formatReport, genesisSummary, globToRegExp, loadConfig, loadGenesis, parseExportNames, parseRulesMarkdown, runDoctor, toJson, validateConfig };
|