@marktiderman/genesis-cli 1.24.0 → 1.26.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.
@@ -23,6 +23,11 @@ interface Finding {
23
23
  * An `allow` entry's `match` is compared against it.
24
24
  */
25
25
  subject?: string;
26
+ /**
27
+ * Every rule that reported this finding, when more than one did (an app rule and a package rule
28
+ * on the same element of the same line): reported once, with `rule` the first of them.
29
+ */
30
+ rules?: string[];
26
31
  }
27
32
  /** What a rule or plugin passes to `report`. `level` defaults to `"error"`. */
28
33
  interface FindingInput {
@@ -42,6 +47,27 @@ interface AllowEntry {
42
47
  match?: string;
43
48
  reason: string;
44
49
  }
50
+ /**
51
+ * A declared extension (`doctor.extend`): a file that builds on one of a package rule's declared
52
+ * extension points (`extensible`) in a way the rule doesn't recognize, and says why. Unlike
53
+ * `allow`, it is not debt: it never expires, and `allow-grew` doesn't count it; a new one is a
54
+ * warning (`extension-added`) for the pull request's review. It covers the findings the file had
55
+ * when it was declared: under `--base`, a count above the merge base's still fails. The doctor
56
+ * checks that `file` still has a finding of `rule` (`stale-extension`), and that `buildsOn` is one
57
+ * of the rule's points, imported from a Genesis package, and flagged by nothing (`extension-invalid`).
58
+ */
59
+ interface ExtensionEntry {
60
+ /** The rule whose findings in `file` it covers. */
61
+ rule: string;
62
+ /** One app-relative file (no globs: each file is reviewed on its own). */
63
+ file: string;
64
+ /** The rule's extension point the file builds on: one of the rule's `extensible` entries (`useBoardColumns`, `ResourceView.slots`). */
65
+ buildsOn: string;
66
+ /** Why the rule's primitive doesn't fit here: a sentence a reviewer can check. */
67
+ reason: string;
68
+ /** Where the gap is written up for Genesis, when it is one (an issue or proposal link). */
69
+ upstream?: string;
70
+ }
45
71
  /** A declarative check: which files it covers and the pattern they must (not) contain. */
46
72
  interface PatternRule {
47
73
  id: string;
@@ -57,7 +83,7 @@ interface PatternRule {
57
83
  /** Regular expression every matching file's path must fit. */
58
84
  path?: string;
59
85
  message?: string;
60
- /** Under `--base`, findings in files unchanged since the merge base drop to `info`. */
86
+ /** Under `--base`, findings drop to `info` unless they are in a new file or their count in a file grew since the merge base. */
61
87
  newOnly?: boolean;
62
88
  }
63
89
  /**
@@ -158,8 +184,9 @@ interface DoctorConfig {
158
184
  */
159
185
  packageRules?: Record<string, PackageRuleSetting>;
160
186
  /**
161
- * With `--base`, findings in files unchanged since the merge base drop to `info`, so new
162
- * code meets the rule and old code is ratcheted. `true` for every rule, or a list of rule ids.
187
+ * With `--base`, a rule's findings drop to `info` unless they are in a new file or a file
188
+ * now has more of them than at the merge base, so new code meets the rule and old code is
189
+ * ratcheted. `true` for every rule, or a list of rule ids.
163
190
  * Rules declared `newOnly` (package rules, app patterns) ratchet without this.
164
191
  */
165
192
  ratchet?: boolean | string[];
@@ -167,8 +194,10 @@ interface DoctorConfig {
167
194
  contracts?: ContractsConfig;
168
195
  /** Per-rule level overrides, e.g. `{ "raw-color": "warn", "palette-color": "off" }`. `info` never fails a run. */
169
196
  rules?: Record<string, RuleSetting>;
170
- /** Justified exceptions. */
197
+ /** Justified exceptions: debt, which only shrinks under `--base`. */
171
198
  allow?: AllowEntry[];
199
+ /** Declared extensions: files that build on Genesis in a way a rule doesn't recognize, reviewed, never expiring. */
200
+ extend?: ExtensionEntry[];
172
201
  /** Declarative app rules. */
173
202
  patterns?: PatternRule[];
174
203
  /** A markdown file of pattern rules (`### rule-id` blocks of `- key: value` lines). */
@@ -202,6 +231,13 @@ interface GenesisFacts {
202
231
  components: readonly string[];
203
232
  /** Custom properties the theme stylesheets define. */
204
233
  tokens: ReadonlySet<string>;
234
+ /**
235
+ * The colour roles among them: tokens whose value is a colour (`--primary: 243 75% 59%`,
236
+ * `--color-primary: hsl(var(--primary))`). Absent when not read.
237
+ */
238
+ colorTokens?: ReadonlySet<string>;
239
+ /** The part names genesis-ui renders (`THEME_PARTS`), from the installed design system. Absent when not found. */
240
+ themeParts?: readonly string[];
205
241
  /** Raw HTML tag → the Genesis component that replaces it. */
206
242
  rawTags: ReadonlyMap<string, string>;
207
243
  /** Tailwind palette color names (red, slate, …). */
@@ -266,6 +302,8 @@ interface DoctorResult {
266
302
  warnings: number;
267
303
  /** Findings at `info`: shown, never failing. */
268
304
  infos: number;
305
+ /** Under `--base`: the declared extensions this branch adds, for the pull request's review (also `extension-added` findings). */
306
+ extensionsAdded?: ExtensionEntry[];
269
307
  }
270
308
  /** One "use X instead of Y" rule, as a package declares it. */
271
309
  interface PreferRule {
@@ -293,6 +331,11 @@ interface PreferRule {
293
331
  unless?: {
294
332
  /** The file renders one of these elements. */
295
333
  renders?: string[];
334
+ /**
335
+ * Not the whole file: a forbidden element nested inside one of these elements, or inside an app
336
+ * component the file imports whose own body renders one, is left alone (a builder's own panels).
337
+ */
338
+ inside?: string[];
296
339
  /** The file contains this regular expression. */
297
340
  pattern?: string;
298
341
  };
@@ -304,8 +347,14 @@ interface PreferRule {
304
347
  docs?: string;
305
348
  /** Why, in a sentence. */
306
349
  why: string;
307
- /** Under `--base`, findings in files unchanged since the merge base drop to `info`. */
350
+ /** Under `--base`, findings drop to `info` unless they are in a new file or their count in a file grew since the merge base. */
308
351
  newOnly?: boolean;
352
+ /**
353
+ * The Genesis exports (or parts of one: `ResourceView.slots`) an app may build on in a way the
354
+ * rule doesn't recognize, and declare as an extension (`doctor.extend`). A rule without them
355
+ * can't be extended.
356
+ */
357
+ extensible?: string[];
309
358
  }
310
359
  /** A catalog entry with no rule behind it. */
311
360
  interface PrimitiveEntry {
@@ -455,4 +504,4 @@ declare function validateLinks(raw: unknown, source?: string): GenesisLinks;
455
504
  /** Check the shape, so a typo fails loudly instead of silently disabling a check. */
456
505
  declare function validateConfig(raw: unknown, source?: string): DoctorConfig;
457
506
 
458
- export { type AllowEntry as A, type SupabasePackConfig as B, type CompanionPackage as C, type DoctorConfig as D, loadConfig as E, type Finding as F, type GenesisDataUse as G, validateConfig as H, 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 GenesisSupabase as k, type GenesisFacts as l, type PatternRule as m, type PreferRule as n, type DeclaringPackage as o, privacyDataType as p, type PackageDeclaration as q, readGenesisConfig as r, type ContractsConfig as s, type DoctorPack as t, type FindingInput as u, validateLinks as v, type PackageRuleSetting as w, type PackagesPackConfig as x, type PluginSpec as y, type PrimitiveEntry as z };
507
+ export { type AllowEntry as A, type SupabasePackConfig as B, type CompanionPackage as C, type DoctorConfig as D, type ExtensionEntry as E, type Finding as F, type GenesisDataUse as G, loadConfig as H, validateConfig as I, 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 GenesisSupabase as k, type GenesisFacts as l, type PatternRule as m, type PreferRule as n, type DeclaringPackage as o, privacyDataType as p, type PackageDeclaration as q, readGenesisConfig as r, type FindingInput as s, type ContractsConfig as t, type DoctorPack as u, validateLinks as v, type PackageRuleSetting as w, type PackagesPackConfig as x, type PluginSpec as y, type PrimitiveEntry as z };
package/dist/doctor.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { D as DoctorConfig, l as GenesisFacts, m as PatternRule, h as DoctorPlugin, S as SourceFile, g as DoctorContext, n as PreferRule, o as DeclaringPackage, q as PackageDeclaration, i as DoctorResult, F as Finding } from './config-DRHg7V3Z.js';
2
- export { A as AllowEntry, C as CompanionPackage, s as ContractsConfig, f as DoctorConfigError, t as DoctorPack, u as FindingInput, c as GenesisConfigError, j as GenesisConfigFile, b as GenesisLinks, k as GenesisSupabase, L as Level, N as NativePackConfig, w as PackageRuleSetting, x as PackagesPackConfig, y as PluginSpec, z as PrimitiveEntry, R as RuleSetting, B as SupabasePackConfig, E as loadConfig, r as readGenesisConfig, H as validateConfig, v as validateLinks } from './config-DRHg7V3Z.js';
1
+ import { D as DoctorConfig, l as GenesisFacts, m as PatternRule, h as DoctorPlugin, S as SourceFile, g as DoctorContext, n as PreferRule, o as DeclaringPackage, q as PackageDeclaration, F as Finding, s as FindingInput, E as ExtensionEntry, i as DoctorResult } from './config-ARs2YQ60.js';
2
+ export { A as AllowEntry, C as CompanionPackage, t as ContractsConfig, f as DoctorConfigError, u as DoctorPack, c as GenesisConfigError, j as GenesisConfigFile, b as GenesisLinks, k as GenesisSupabase, L as Level, N as NativePackConfig, w as PackageRuleSetting, x as PackagesPackConfig, y as PluginSpec, z as PrimitiveEntry, R as RuleSetting, B as SupabasePackConfig, H as loadConfig, r as readGenesisConfig, I as validateConfig, v as validateLinks } from './config-ARs2YQ60.js';
3
3
  import '@marktiderman/genesis-features';
4
4
 
5
5
  /** The installed folder of `name`, looking in node_modules from `from` upward (works with hoisting and pnpm). */
@@ -27,7 +27,7 @@ declare function parseRulesMarkdown(markdown: string): PatternRule[];
27
27
  declare function defineDoctorPlugin(plugin: DoctorPlugin): DoctorPlugin;
28
28
 
29
29
  /** Ids of the built-in rules, for `rules` overrides and `allow` entries. */
30
- declare const BUILTIN_RULES: readonly ["local-primitives", "figma-routes", "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", "deprecated-import", "beta-import", "native-raw-primitive", "native-literal-color", "native-custom-header", "native-screen-layout", "store-readiness", "eas-placeholder", "migration-grants", "migration-rls", "migration-definer-search-path", "migration-edited", "migration-testing-kit", "migration-view-rls", "exposed-schema-created-later", "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", "overlay-unmarked", "overlay-invalid", "overlay-age", "overlay-version", "overlay-behind", "package-rules-invalid", "package-rule-override", "ratchet-skipped", "allow-grew", "rules-weakened", "agent-guide-stale", "contracts-stale", "lock-files", "database-elsewhere", "genesis-eslint-config"];
30
+ declare const BUILTIN_RULES: readonly ["local-primitives", "figma-routes", "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", "deprecated-import", "beta-import", "native-raw-primitive", "native-literal-color", "native-custom-header", "native-screen-layout", "store-readiness", "eas-placeholder", "migration-grants", "migration-rls", "migration-definer-search-path", "migration-edited", "migration-testing-kit", "migration-view-rls", "exposed-schema-created-later", "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", "overlay-unmarked", "overlay-invalid", "overlay-age", "overlay-version", "overlay-behind", "package-rules-invalid", "package-rule-override", "ratchet-skipped", "allow-grew", "rules-weakened", "extension-added", "stale-extension", "extension-invalid", "agent-guide-stale", "contracts-stale", "lock-files", "database-elsewhere", "genesis-eslint-config", "app-part-colors", "app-part-name", "custom-view-states"];
31
31
 
32
32
  /**
33
33
  * Minimal globs for config: `*` matches within a folder, `**` across folders,
@@ -244,6 +244,35 @@ declare const BLOCKED_FIX = "rename or replace it with a CLAUDE.md file (or remo
244
244
  */
245
245
  declare function changedSince(root: string, base: string): Set<string> | null;
246
246
 
247
+ interface ExtensionContext {
248
+ config: DoctorConfig;
249
+ files: readonly SourceFile[];
250
+ packages: readonly DeclaringPackage[];
251
+ /** Every finding the rules reported, before `rules`, `allow` and extensions applied. */
252
+ raw: readonly FindingInput[];
253
+ /**
254
+ * How many findings an extension may cover: its file's count of its rule at the merge base, for
255
+ * an extension the base config had too. Undefined: no limit (no `--base`, or a new extension,
256
+ * whose findings the pull request's review sees).
257
+ */
258
+ limit?: (entry: ExtensionEntry) => number | undefined;
259
+ }
260
+ /** Why an extension can't be accepted, or null when it can. */
261
+ declare function extensionProblem(entry: ExtensionEntry, ctx: Omit<ExtensionContext, "limit">): string | null;
262
+ /**
263
+ * Drop the findings each valid extension covers, and report extensions that no longer cover
264
+ * anything (`stale-extension`) or can't be accepted (`extension-invalid`). Runs after `rules` and
265
+ * `allow`, so an extension of a rule that is off isn't reported. With `limit`, a file that has
266
+ * more findings of the rule than the extension covered at the merge base keeps them all.
267
+ */
268
+ declare function applyExtensions(findings: Finding[], ctx: ExtensionContext): Finding[];
269
+ /**
270
+ * One finding per element: findings of different rules on the same file, line and subject (an
271
+ * app's own rule and a package rule hitting the same `<DataTable>`) are merged, at the higher
272
+ * level, listing every rule in `rules`. Two findings of one rule stay two (two elements on a line).
273
+ */
274
+ declare function dedupeFindings(findings: readonly Finding[]): Finding[];
275
+
247
276
  /** The `source` line `genesis introspect` writes for a Postgres read. Shared so the check and the command agree. */
248
277
  declare const postgresSource: (schemas: readonly string[]) => string;
249
278
  /** The contract `genesis introspect` writes for these schemas, read from Postgres. */
@@ -329,6 +358,7 @@ declare function formatReport(result: DoctorResult, options?: {
329
358
  }): string;
330
359
  /** The `--json` report: plain data, sets turned into sorted lists. */
331
360
  declare function toJson(result: DoctorResult): {
361
+ extensionsAdded?: ExtensionEntry[] | undefined;
332
362
  ok: boolean;
333
363
  genesis: string;
334
364
  errors: number;
@@ -355,4 +385,4 @@ declare function genesisSummary(g: GenesisFacts): {
355
385
  };
356
386
  };
357
387
 
358
- export { BLOCKED_FIX, BUILTIN_RULES, CLAUDE_IMPORT, DENY_RULES, DeclaringPackage, DoctorConfig, DoctorContext, DoctorPlugin, DoctorResult, Finding, GenesisFacts, type GenesisInstall, PackageDeclaration, PackageDeclarationError, type PackageGuide, PatternRule, PreferRule, type PrimitiveRow, type ReleaseManifest, type ResolvedPreferRule, type RouteFile, type RunDoctorOptions, SETTINGS_PATH, SKILL_PATH, SUBAGENT_HOOK_COMMAND, SourceFile, agentGuideState, agentHooksState, agentRules, builtinChecks, catalogTable, changedSince, clearPackageRulesCache, defineDoctorPlugin, discoverPackages, findPackageDir, formatPrimitives, formatReport, genesisInstalls, genesisSummary, globToRegExp, loadGenesis, mergeAgentHooks, nativeLayouts, packageGuides, parseExportNames, parseRulesMarkdown, postgresContract, postgresSource, preferRules, primitivesCatalog, primitivesSummary, readPackageExports, readReleaseManifest, renderAgentsBlock, renderSkill, routesDir, ruleNamespace, runDoctor, satisfies, skillDescription, sqlStatements, subagentContext, subagentHookOutput, toJson, unlistedGuides, validateDeclaration, webRoutes, writeAgentGuide, writeAgentHooks };
388
+ export { BLOCKED_FIX, BUILTIN_RULES, CLAUDE_IMPORT, DENY_RULES, DeclaringPackage, DoctorConfig, DoctorContext, DoctorPlugin, DoctorResult, ExtensionEntry, Finding, FindingInput, GenesisFacts, type GenesisInstall, PackageDeclaration, PackageDeclarationError, type PackageGuide, PatternRule, PreferRule, type PrimitiveRow, type ReleaseManifest, type ResolvedPreferRule, type RouteFile, type RunDoctorOptions, SETTINGS_PATH, SKILL_PATH, SUBAGENT_HOOK_COMMAND, SourceFile, agentGuideState, agentHooksState, agentRules, applyExtensions, builtinChecks, catalogTable, changedSince, clearPackageRulesCache, dedupeFindings, defineDoctorPlugin, discoverPackages, extensionProblem, findPackageDir, formatPrimitives, formatReport, genesisInstalls, genesisSummary, globToRegExp, loadGenesis, mergeAgentHooks, nativeLayouts, packageGuides, parseExportNames, parseRulesMarkdown, postgresContract, postgresSource, preferRules, primitivesCatalog, primitivesSummary, readPackageExports, readReleaseManifest, renderAgentsBlock, renderSkill, routesDir, ruleNamespace, runDoctor, satisfies, skillDescription, sqlStatements, subagentContext, subagentHookOutput, toJson, unlistedGuides, validateDeclaration, webRoutes, writeAgentGuide, writeAgentHooks };