@marktiderman/genesis-cli 1.14.0 → 1.15.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.
@@ -54,6 +54,29 @@ interface PatternRule {
54
54
  /** Regular expression every matching file's path must fit. */
55
55
  path?: string;
56
56
  message?: string;
57
+ /** Under `--base`, findings in files unchanged since the merge base drop to `info`. */
58
+ newOnly?: boolean;
59
+ }
60
+ /**
61
+ * An app's setting for one package rule (`doctor.packageRules["ui/lists-use-resource-view"]`).
62
+ * `reason` is required: a package rule is never changed silently.
63
+ */
64
+ interface PackageRuleSetting {
65
+ level?: RuleSetting;
66
+ /** Replace the rule's own file globs (`{routes}` is the routes folder). */
67
+ files?: string[];
68
+ /** Replace the rule's own exclusions. */
69
+ exclude?: string[];
70
+ reason: string;
71
+ }
72
+ /** `doctor.contracts`: the generated contract the supabase pack keeps current (as `genesis introspect --check`). */
73
+ interface ContractsConfig {
74
+ /** The contract file, app-relative. Default `resources.genesis.ts`. */
75
+ out?: string;
76
+ /** Schemas to read. Default `["public"]`. */
77
+ schemas?: string[];
78
+ /** The environment variable holding the Postgres URL. Default `DATABASE_URL`. Without it the check is skipped (info). */
79
+ databaseEnv?: string;
57
80
  }
58
81
  /** A plugin entry in config: a module path, or `[path, options]`. */
59
82
  type PluginSpec = string | [string, unknown];
@@ -120,6 +143,19 @@ interface DoctorConfig {
120
143
  forbiddenImports?: Record<string, string>;
121
144
  /** Folders that must not exist (local design-system primitives). Default `["src/components/ui"]`. */
122
145
  localPrimitiveDirs?: string[];
146
+ /**
147
+ * Settings for package rules (the rules Genesis packages declare, ids like `ui/lists-use-resource-view`):
148
+ * level, files and exclusions, each with a reason.
149
+ */
150
+ packageRules?: Record<string, PackageRuleSetting>;
151
+ /**
152
+ * With `--base`, findings in files unchanged since the merge base drop to `info`, so new
153
+ * code meets the rule and old code is ratcheted. `true` for every rule, or a list of rule ids.
154
+ * Rules declared `newOnly` (package rules, app patterns) ratchet without this.
155
+ */
156
+ ratchet?: boolean | string[];
157
+ /** The generated contract the supabase pack checks is current. */
158
+ contracts?: ContractsConfig;
123
159
  /** Per-rule level overrides, e.g. `{ "raw-color": "warn", "palette-color": "off" }`. `info` never fails a run. */
124
160
  rules?: Record<string, RuleSetting>;
125
161
  /** Justified exceptions. */
@@ -191,6 +227,8 @@ interface DoctorContext {
191
227
  config: DoctorConfig;
192
228
  /** The git ref change checks compare against (`--base`), when given. */
193
229
  base?: string;
230
+ /** The Genesis and local packages whose declared rules run, with their declarations. */
231
+ packages: readonly DeclaringPackage[];
194
232
  /** Record a finding. Config `rules` levels and `allow` entries apply afterwards. */
195
233
  report(finding: FindingInput): void;
196
234
  }
@@ -208,11 +246,91 @@ interface DoctorResult {
208
246
  unused: string[];
209
247
  /** Pattern rules plus plugins that ran. */
210
248
  ruleCount: number;
249
+ /** Rules the installed packages declare, and how many packages declare them. */
250
+ primitives: {
251
+ rules: number;
252
+ packages: number;
253
+ };
211
254
  errors: number;
212
255
  warnings: number;
213
256
  /** Findings at `info`: shown, never failing. */
214
257
  infos: number;
215
258
  }
259
+ /** One "use X instead of Y" rule, as a package declares it. */
260
+ interface PreferRule {
261
+ /** Local id; the doctor namespaces it by package (`ui/<id>`). Lower-case words and dashes. */
262
+ id: string;
263
+ /** The need it answers, for the primitives catalog ("a list screen"). */
264
+ need?: string;
265
+ /** Default `warn`. */
266
+ level?: Level;
267
+ /** Web apps only, native (Expo, the `native` pack) only, or both (default). */
268
+ platform?: "web" | "native";
269
+ /** App-relative globs. `{routes}` stands for the app's routes folder. Default: every scanned script file. */
270
+ files?: string[];
271
+ exclude?: string[];
272
+ /** What the rule flags. At least one. Comments never count. */
273
+ forbid: {
274
+ /** JSX element names (`<DataTable`). */
275
+ jsx?: string[];
276
+ /** Import specifiers: exact, or ending in `*` for a prefix (`@supabase/*`). */
277
+ imports?: string[];
278
+ /** A regular expression (every match is reported). Prefix `(?i)` for case-insensitive. */
279
+ pattern?: string;
280
+ };
281
+ /** A file that matches any of these is left alone (it is the primitive, or builds on it). */
282
+ unless?: {
283
+ /** The file renders one of these elements. */
284
+ renders?: string[];
285
+ /** The file contains this regular expression. */
286
+ pattern?: string;
287
+ };
288
+ /** What to use instead. */
289
+ use: string;
290
+ /** Where it comes from. */
291
+ import?: string;
292
+ /** A link to the docs. */
293
+ docs?: string;
294
+ /** Why, in a sentence. */
295
+ why: string;
296
+ /** Under `--base`, findings in files unchanged since the merge base drop to `info`. */
297
+ newOnly?: boolean;
298
+ }
299
+ /** A catalog entry with no rule behind it. */
300
+ interface PrimitiveEntry {
301
+ need: string;
302
+ use: string;
303
+ import?: string;
304
+ docs?: string;
305
+ }
306
+ /** A package's validated `genesis.doctor` declaration. */
307
+ interface PackageDeclaration {
308
+ enforce: boolean;
309
+ /** Why a package enforces nothing (required when `enforce` is false). */
310
+ reason?: string;
311
+ prefer: PreferRule[];
312
+ primitives: PrimitiveEntry[];
313
+ /** A rule module in the package (absolute path), loaded like an app plugin. */
314
+ plugin?: string;
315
+ }
316
+ /** A package the doctor read declarations from. */
317
+ interface DeclaringPackage {
318
+ name: string;
319
+ version: string;
320
+ /** Absolute folder (as found, not resolved through links). */
321
+ dir: string;
322
+ /** The prefix of its rule ids (`ui` for genesis-ui). */
323
+ namespace: string;
324
+ local: boolean;
325
+ /** Not published (`private: true`). */
326
+ private: boolean;
327
+ /** Null when the package declares nothing. */
328
+ declaration: PackageDeclaration | null;
329
+ /** Why its declaration was refused, when it was. */
330
+ error?: string;
331
+ /** What was left out of an accepted declaration (unknown keys, rules that don't validate), when anything was. */
332
+ ignored?: string[];
333
+ }
216
334
 
217
335
  /** A genesis.config.json that can't be read or has a block of the wrong shape. */
218
336
  declare class GenesisConfigError extends Error {
@@ -298,4 +416,4 @@ declare function validateLinks(raw: unknown, source?: string): GenesisLinks;
298
416
  /** Check the shape, so a typo fails loudly instead of silently disabling a check. */
299
417
  declare function validateConfig(raw: unknown, source?: string): DoctorConfig;
300
418
 
301
- export { type AllowEntry as A, type CompanionPackage as C, type DoctorConfig as D, type Finding as F, type GenesisDataUse as G, type Level as L, type NativePackConfig as N, PRIVACY_DATA_TYPES as P, type RuleSetting as R, type SourceFile as S, type GenesisPrivacy as a, type GenesisLinks as b, GenesisConfigError as c, PRIVACY_PURPOSES as d, validatePrivacy as e, DoctorConfigError as f, type DoctorContext as g, type DoctorPlugin as h, type DoctorResult as i, type GenesisConfigFile as j, type GenesisFacts as k, type PatternRule as l, type DoctorPack as m, type FindingInput as n, type PackagesPackConfig as o, privacyDataType as p, type PluginSpec as q, readGenesisConfig as r, type SupabasePackConfig as s, loadConfig as t, validateConfig as u, validateLinks as v };
419
+ export { type AllowEntry as A, loadConfig as B, type CompanionPackage as C, type DoctorConfig as D, validateConfig as E, type Finding as F, type GenesisDataUse as G, type Level as L, type NativePackConfig as N, PRIVACY_DATA_TYPES as P, type RuleSetting as R, type SourceFile as S, type GenesisPrivacy as a, type GenesisLinks as b, GenesisConfigError as c, PRIVACY_PURPOSES as d, validatePrivacy as e, DoctorConfigError as f, type DoctorContext as g, type DoctorPlugin as h, type DoctorResult as i, type GenesisConfigFile as j, type GenesisFacts as k, type PatternRule as l, type PreferRule as m, type DeclaringPackage as n, type PackageDeclaration as o, privacyDataType as p, type ContractsConfig as q, readGenesisConfig as r, type DoctorPack as s, type FindingInput as t, type PackageRuleSetting as u, validateLinks as v, type PackagesPackConfig as w, type PluginSpec as x, type PrimitiveEntry as y, type SupabasePackConfig as z };
package/dist/doctor.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { D as DoctorConfig, k as GenesisFacts, l as PatternRule, h as DoctorPlugin, S as SourceFile, g as DoctorContext, i as DoctorResult, F as Finding } from './config-4MhgqkFT.js';
2
- export { A as AllowEntry, C as CompanionPackage, f as DoctorConfigError, m as DoctorPack, n as FindingInput, c as GenesisConfigError, j as GenesisConfigFile, b as GenesisLinks, L as Level, N as NativePackConfig, o as PackagesPackConfig, q as PluginSpec, R as RuleSetting, s as SupabasePackConfig, t as loadConfig, r as readGenesisConfig, u as validateConfig, v as validateLinks } from './config-4MhgqkFT.js';
1
+ import { D as DoctorConfig, k as GenesisFacts, l as PatternRule, h as DoctorPlugin, S as SourceFile, g as DoctorContext, m as PreferRule, n as DeclaringPackage, o as PackageDeclaration, i as DoctorResult, F as Finding } from './config-DewJ3DR6.js';
2
+ export { A as AllowEntry, C as CompanionPackage, q as ContractsConfig, f as DoctorConfigError, s as DoctorPack, t as FindingInput, c as GenesisConfigError, j as GenesisConfigFile, b as GenesisLinks, L as Level, N as NativePackConfig, u as PackageRuleSetting, w as PackagesPackConfig, x as PluginSpec, y as PrimitiveEntry, R as RuleSetting, z as SupabasePackConfig, B as loadConfig, r as readGenesisConfig, E as validateConfig, v as validateLinks } from './config-DewJ3DR6.js';
3
3
 
4
4
  /** The installed folder of `name`, looking in node_modules from `from` upward (works with hoisting and pnpm). */
5
5
  declare function findPackageDir(from: string, name: string): string | null;
@@ -26,7 +26,7 @@ declare function parseRulesMarkdown(markdown: string): PatternRule[];
26
26
  declare function defineDoctorPlugin(plugin: DoctorPlugin): DoctorPlugin;
27
27
 
28
28
  /** Ids of the built-in rules, for `rules` overrides and `allow` entries. */
29
- declare const BUILTIN_RULES: readonly ["local-primitives", "starter-leftover", "forbidden-import", "raw-tag", "palette-color", "arbitrary-color", "raw-color", "undefined-token", "shadowed-export", "version-skew", "duplicate-genesis-package", "peer-range-mismatch", "hand-rolled-sub-nav", "local-genesis-copy", "resource-workspace", "page-layout", "iso-date-slice", "resource-view-tree", "studio-server-auth-import", "removed-scope-name", "scope-practice-id", "native-raw-primitive", "native-literal-color", "native-custom-header", "native-screen-layout", "store-readiness", "migration-grants", "migration-rls", "migration-definer-search-path", "migration-edited", "migration-testing-kit", "migration-view-rls", "package-app-import", "package-undeclared-dependency", "package-migration-test", "package-migration-number", "package-migration-edited", "package-unregistered", "package-unversioned-change", "package-export-missing", "package-block-invalid", "package-untagged-tests"];
29
+ declare const BUILTIN_RULES: readonly ["local-primitives", "starter-leftover", "forbidden-import", "raw-tag", "palette-color", "arbitrary-color", "raw-color", "undefined-token", "shadowed-export", "version-skew", "duplicate-genesis-package", "peer-range-mismatch", "hand-rolled-sub-nav", "local-genesis-copy", "resource-workspace", "page-layout", "iso-date-slice", "resource-view-tree", "studio-server-auth-import", "removed-scope-name", "scope-practice-id", "native-raw-primitive", "native-literal-color", "native-custom-header", "native-screen-layout", "store-readiness", "migration-grants", "migration-rls", "migration-definer-search-path", "migration-edited", "migration-testing-kit", "migration-view-rls", "package-app-import", "package-undeclared-dependency", "package-migration-test", "package-migration-number", "package-migration-edited", "package-unregistered", "package-unversioned-change", "package-export-missing", "package-block-invalid", "package-untagged-tests", "package-doctor-declaration", "package-rules-invalid", "package-rule-override", "ratchet-skipped", "allow-grew", "rules-weakened", "agent-guide-stale", "contracts-stale"];
30
30
 
31
31
  /**
32
32
  * Minimal globs for config: `*` matches within a folder, `**` across folders,
@@ -137,6 +137,90 @@ declare function routesDir(ctx: Pick<DoctorContext, "root" | "config">): string
137
137
  /** Every scanned JSX route file under the routes folder, with its layouts. Empty without one. */
138
138
  declare function webRoutes(ctx: Pick<DoctorContext, "root" | "config" | "files">): RouteFile[];
139
139
 
140
+ declare class PackageDeclarationError extends Error {
141
+ name: string;
142
+ }
143
+ /** `ui` for `@marktiderman/genesis-ui`, `genesis` for the umbrella, the full name for anything else. */
144
+ declare function ruleNamespace(packageName: string): string;
145
+ /**
146
+ * Check one package's `genesis.doctor` value and return it normalized. Throws a
147
+ * PackageDeclarationError naming the package and the key that's wrong.
148
+ *
149
+ * With `ignored`, it reads forward-compatibly, as an app's doctor reads installed packages: a
150
+ * package may be newer than this CLI, so an unknown key, or a `prefer` rule or primitive that
151
+ * doesn't validate, is left out and described in `ignored` instead of refusing the declaration.
152
+ */
153
+ declare function validateDeclaration(raw: unknown, packageName: string, packageDir?: string, ignored?: string[]): PackageDeclaration;
154
+ /**
155
+ * Every package whose rules apply to the app: the installed Genesis packages
156
+ * (and the Genesis packages installed beside them, for an isolated install), and the app's local packages (a local package wins over an installed one
157
+ * of the same name). Sorted by name.
158
+ */
159
+ declare function discoverPackages(root: string): DeclaringPackage[];
160
+ /** Forget what was read (tests). */
161
+ declare function clearPackageRulesCache(): void;
162
+ /** A package rule with its namespaced id and the package it came from. */
163
+ interface ResolvedPreferRule extends PreferRule {
164
+ /** `ui/lists-use-resource-view`. */
165
+ ruleId: string;
166
+ package: string;
167
+ packageDir: string;
168
+ }
169
+ /** The prefer rules of every package that declares any. */
170
+ declare function preferRules(packages: readonly DeclaringPackage[]): ResolvedPreferRule[];
171
+
172
+ /** One row of the catalog. */
173
+ interface PrimitiveRow {
174
+ need: string;
175
+ use: string;
176
+ import?: string;
177
+ docs?: string;
178
+ /** The rule that enforces it, when one does. */
179
+ rule?: string;
180
+ /** Where the row comes from: a package name, or `genesis-cli` for the static core. */
181
+ from: string;
182
+ }
183
+ /** The catalog: the static core, then each package's rules and primitives, in package order. */
184
+ declare function primitivesCatalog(packages: readonly DeclaringPackage[]): PrimitiveRow[];
185
+ /** How many rules the packages declare, and how many packages declare at least one. */
186
+ declare function primitivesSummary(packages: readonly DeclaringPackage[]): {
187
+ rules: number;
188
+ packages: number;
189
+ };
190
+ /** The catalog as a Markdown table. */
191
+ declare function catalogTable(rows: readonly PrimitiveRow[], options?: {
192
+ docs?: boolean;
193
+ }): string;
194
+ /** `genesis primitives`: the catalog for a terminal. */
195
+ declare function formatPrimitives(rows: readonly PrimitiveRow[]): string;
196
+ declare const SKILL_PATH = ".claude/skills/genesis/SKILL.md";
197
+ /** `.claude/skills/genesis/SKILL.md`, generated. */
198
+ declare function renderSkill(rows: readonly PrimitiveRow[]): string;
199
+ /** The AGENTS.md block, generated (markers included). */
200
+ declare function renderAgentsBlock(rows: readonly PrimitiveRow[]): string;
201
+ /** `genesis agents`: write the skill and the AGENTS.md block. Returns the files it changed. Writes nothing when AGENTS.md's block is broken. */
202
+ declare function writeAgentGuide(root: string, packages: readonly DeclaringPackage[], agentsFile?: string): string[];
203
+ /** What `agent-guide-stale` found: the generated files that are missing or differ. */
204
+ declare function agentGuideState(root: string, packages: readonly DeclaringPackage[], agentsFile?: string): {
205
+ skill: "ok" | "missing" | "stale";
206
+ agents: "ok" | "missing" | "stale" | "broken";
207
+ };
208
+
209
+ /**
210
+ * App-relative paths changed since the merge base with `base`: committed on
211
+ * this branch, staged, unstaged or untracked. Null when git can't tell (not a
212
+ * repository, or the ref isn't there).
213
+ */
214
+ declare function changedSince(root: string, base: string): Set<string> | null;
215
+
216
+ /** The `source` line `genesis introspect` writes for a Postgres read. Shared so the check and the command agree. */
217
+ declare const postgresSource: (schemas: readonly string[]) => string;
218
+ /** The contract `genesis introspect` writes for these schemas, read from Postgres. */
219
+ declare function postgresContract(url: string, schemas: string[]): Promise<{
220
+ content: string;
221
+ tables: number;
222
+ }>;
223
+
140
224
  interface RunDoctorOptions {
141
225
  /** The app root. Default `process.cwd()`. */
142
226
  root?: string;
@@ -152,8 +236,12 @@ interface RunDoctorOptions {
152
236
  quietBuild?: boolean;
153
237
  /** Reuse facts read earlier (the Vite dev server caches them). */
154
238
  genesis?: GenesisFacts;
155
- /** The git ref change checks compare against (`--base`): the packages pack's change gate. */
239
+ /** The git ref change checks compare against (`--base`): the packages pack's change gate and the ratchet. */
156
240
  base?: string;
241
+ /** Files changed since `base`, app-relative, instead of asking git (tests, or a CI that already knows). */
242
+ changedFiles?: string[];
243
+ /** Run the supabase pack's contract check (it reads the database). Default true; the Vite plugin (build and dev) passes false. */
244
+ contracts?: boolean;
157
245
  }
158
246
  declare function runDoctor(options?: RunDoctorOptions): Promise<DoctorResult>;
159
247
  /**
@@ -161,7 +249,9 @@ declare function runDoctor(options?: RunDoctorOptions): Promise<DoctorResult>;
161
249
  * here plus its ids in BUILTIN_RULES (rules.ts); a pack's checks run only when
162
250
  * `packs` lists it.
163
251
  */
164
- declare function builtinChecks(config: DoctorConfig): DoctorPlugin[];
252
+ declare function builtinChecks(config: DoctorConfig, options?: {
253
+ contracts?: boolean;
254
+ }): DoctorPlugin[];
165
255
  /** The human-readable report. */
166
256
  declare function formatReport(result: DoctorResult): string;
167
257
  /** The `--json` report: plain data, sets turned into sorted lists. */
@@ -173,6 +263,10 @@ declare function toJson(result: DoctorResult): {
173
263
  infos: number;
174
264
  findings: Finding[];
175
265
  unused: string[];
266
+ primitives: {
267
+ rules: number;
268
+ packages: number;
269
+ };
176
270
  };
177
271
  /** What `--print-genesis` shows: the facts every rule is derived from. */
178
272
  declare function genesisSummary(g: GenesisFacts): {
@@ -188,4 +282,4 @@ declare function genesisSummary(g: GenesisFacts): {
188
282
  };
189
283
  };
190
284
 
191
- export { BUILTIN_RULES, DoctorConfig, DoctorContext, DoctorPlugin, DoctorResult, Finding, GenesisFacts, type GenesisInstall, PatternRule, type ReleaseManifest, type RouteFile, type RunDoctorOptions, SourceFile, builtinChecks, defineDoctorPlugin, findPackageDir, formatReport, genesisInstalls, genesisSummary, globToRegExp, loadGenesis, nativeLayouts, parseExportNames, parseRulesMarkdown, readPackageExports, readReleaseManifest, routesDir, runDoctor, satisfies, sqlStatements, toJson, webRoutes };
285
+ export { BUILTIN_RULES, DeclaringPackage, DoctorConfig, DoctorContext, DoctorPlugin, DoctorResult, Finding, GenesisFacts, type GenesisInstall, PackageDeclaration, PackageDeclarationError, PatternRule, PreferRule, type PrimitiveRow, type ReleaseManifest, type ResolvedPreferRule, type RouteFile, type RunDoctorOptions, SKILL_PATH, SourceFile, agentGuideState, builtinChecks, catalogTable, changedSince, clearPackageRulesCache, defineDoctorPlugin, discoverPackages, findPackageDir, formatPrimitives, formatReport, genesisInstalls, genesisSummary, globToRegExp, loadGenesis, nativeLayouts, parseExportNames, parseRulesMarkdown, postgresContract, postgresSource, preferRules, primitivesCatalog, primitivesSummary, readPackageExports, readReleaseManifest, renderAgentsBlock, renderSkill, routesDir, ruleNamespace, runDoctor, satisfies, sqlStatements, toJson, validateDeclaration, webRoutes, writeAgentGuide };