@marktiderman/genesis-cli 1.24.0 → 1.25.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 CHANGED
@@ -798,7 +798,7 @@ Upgrading Genesis upgrades the checks.
798
798
  | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
799
799
  | `-d, --dir <dir>` | The app's folder (default: cwd). |
800
800
  | `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
801
- | `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules report files unchanged since the merge base as `info`). |
801
+ | `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules keep their level only in new files and in files whose count of their findings grew since the merge base; the rest are `info`). |
802
802
 
803
803
  Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built). With the app's dependencies not installed, the message gives the install command.
804
804
 
@@ -831,6 +831,9 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
831
831
  | `figma-routes` | info | Runs only when genesis.config.json has a `figma` block: [genesis figma:routes](#genesis-figmaroutes) as findings. A configured page the file doesn't have, a route with no frame, navigation with no hotspot and a `// figma:` id that isn't the route's frame are `info`, `warn` under `--strict`; frames with no route, hotspots to them and navigation that isn't a string literal are always `info`, by design. Never `error`. Invalid JSON or a bad `figma` block in genesis.config.json is one `warn` naming the file. Without `FIGMA_ACCESS_TOKEN`, or when the API can't be read or doesn't answer within 30 seconds, one `info` notice. The Vite plugin and `genesis upgrade` skip it (it reads the network). |
832
832
  | `scope-practice-id` | info | `scope.practiceId` read with no `ResourceScope` augmentation in the app (declaration files included). It still works, as the app's own key in the open slot, but reads as `unknown`; the message gives the one-line augmentation. Never fails, `--strict` included. |
833
833
  | `stale-exception` | warn | An `allow` entry that no longer matches anything, or a `packageRules` entry that names no rule an installed package declares (a typo there would change nothing). An id in the namespace of a package with a `plugin` isn't checked, since a plugin's ids aren't known until it reports. |
834
+ | `stale-extension` | warn | A [declared extension](#declared-extensions) whose file no longer has a finding of its rule; remove it. Not reported while the rule is `off`. |
835
+ | `extension-invalid` | error | A [declared extension](#declared-extensions) the doctor can't accept: its rule declares no extension points or `buildsOn` isn't one, its file doesn't import `buildsOn` from a Genesis package, `buildsOn` is what a package rule replaces, or something in the file flags it. The findings it would cover stay. `rules` and `allow` can't name it. |
836
+ | `extension-added` | info | Under `--base`: a declared extension the doctor settings at the merge base didn't have (every one, when the base had no doctor settings), with its reason. The report's summary lists them all, and the pull request's review is where each is accepted. Never fails. |
834
837
  | `package-rules-invalid` | warn | An installed or local package's `genesis.doctor` declaration (or its plugin) that doesn't validate: its rules don't run; the rest of the doctor does. Read forward-compatibly, since a package can be newer than the CLI: an unknown key is ignored, and a `prefer` rule or primitive that doesn't validate is skipped on its own, each with this warning. An unknown key on a `prefer` rule itself or in its `unless` could narrow where it applies, so that rule is skipped whole rather than run wider; an unknown key in `forbid` is only dropped. It is never an error, so a package upgrade can't break an app's build. See [Package rules](#package-rules). |
835
838
  | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
836
839
  | `agent-guide-stale` | warn | The agent guide `genesis agents` wrote (`.claude/skills/genesis/SKILL.md` and the `genesis-primitives` block in AGENTS.md) doesn't match the installed packages, one of the two is missing, or the block's markers are broken (one missing, repeated or out of order; `genesis agents` then writes nothing). An app with neither isn't checked. Line endings don't count. |
@@ -1045,13 +1048,19 @@ once). A package that must stay readable by a genesis-cli before this release ke
1045
1048
  | `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
1046
1049
  | `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
1047
1050
  | `forbid` | `jsx` element names (type arguments too: `<ResourcePage<T>`), `imports` (exact, or `prefix*`), and/or a `pattern` regular expression (every match is reported; `(?i)` for case-insensitive). Comments never count. |
1048
- | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. |
1051
+ | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. `inside` exempts elements, not files: a forbidden element nested inside one of these (a builder's own panels inside `BuilderLayout`), or inside an app component the file imports that renders its `{children}` inside one. Tags in strings and template literals don't count. |
1052
+ | `extensible` | The rule's extension points: the Genesis exports (or parts of one, `ResourceView.slots`) an app may build on in a way the rule doesn't recognize, and record as a [declared extension](#declared-extensions). A rule without them can't be extended. Needs genesis-cli 1.25 or later (an older one skips a rule with this key, with a `package-rules-invalid` warning). |
1049
1053
  | `use`, `import`, `docs`, `why` | The message: what to use, where from, why, and the link. `use` and `why` are required. |
1050
- | `newOnly` | Ratchet: under `--base`, findings in unchanged files drop to `info`. |
1054
+ | `newOnly` | Ratchet: under `--base`, findings drop to `info` unless they are in a new file or a file now has more of them than at the merge base. |
1051
1055
 
1052
1056
  A forbidden element counts one level up too: an app component that renders it (`RecordTable`
1053
1057
  around `DataTable`) is flagged in its own file, and so is every screen that renders the
1054
- wrapper. A package's rules never run on the package's own files.
1058
+ wrapper. `unless.inside` follows the same level, for the elements nested in it only. A package's
1059
+ rules never run on the package's own files.
1060
+
1061
+ When two rules flag the same element on the same line (an app's own rule and a package rule,
1062
+ say), the doctor reports it once, at the higher level, with every rule id in `rules` (and in the
1063
+ report's brackets).
1055
1064
 
1056
1065
  A package with nothing to enforce says so, with a reason, and may still list primitives:
1057
1066
  `"doctor": { "enforce": false, "reason": "Development tooling, not app screens." }`. In the
@@ -1092,19 +1101,29 @@ since the catalog would leave it out. Run `genesis agents` after each Genesis up
1092
1101
  ### The ratchet
1093
1102
 
1094
1103
  `newOnly` rules (package rules and app patterns can declare it), and any rule the app lists in
1095
- `doctor.ratchet` (`true` for all), apply in full only to new and changed code: with
1096
- `--base <ref>`, a finding in a file unchanged since the merge base is reported as `info`, with
1097
- "ratcheted" in its message. Changed means committed on the branch, staged, edited or
1098
- untracked. Without `--base` every rule runs at its level, as before; when git can't compare,
1104
+ `doctor.ratchet` (`true` for all), apply in full only to new code: with `--base <ref>`, the
1105
+ doctor counts each file's findings of each ratcheted rule at the merge base and now. A finding
1106
+ keeps its level only in a file the merge base didn't have, or in a file that now has more of
1107
+ that rule's findings than it had; everything else is reported as `info`, with "ratcheted" in its
1108
+ message. So a one-line fix in a file with old debt passes, and adding to the debt doesn't.
1109
+ Counts are per rule and file, not per finding: fixing one finding and adding another of the same
1110
+ rule in the same file nets out, and the new one is reported as `info` like the rest. A renamed or
1111
+ moved file keeps its count (git's rename detection). A copy doesn't: its findings are new debt,
1112
+ even when the debt moved out of the file it was copied from.
1113
+ Changed means committed on the branch, staged, edited or untracked; the merge base's counts come
1114
+ from the changed files as git has them there: only the package rules run again on them when
1115
+ every rule being counted is one (the usual case), else every check that reads the app's files;
1116
+ never the build, the database contract or Figma. When git can't read them, a changed file keeps
1117
+ every level. Without `--base` every rule runs at its level, as before; when git can't compare,
1099
1118
  `ratchet-skipped` says so and nothing is lowered. `allow` entries still remove findings,
1100
1119
  ratcheted or not: they are the recorded ratchet, file by file, and under `--base` the list only
1101
1120
  shrinks: `allow-grew` fails an entry the doctor settings at the merge base didn't have, and
1102
1121
  `rules-weakened` fails a rule the base's settings set that this branch lowers, turns off or
1103
1122
  excludes files from (compared with the base's settings only). Neither runs when the base had no
1104
1123
  doctor settings. These two and
1105
- `ratchet-skipped` guard the config itself, so `rules` and `allow` can't name them (the config is
1124
+ `ratchet-skipped` (and `extension-invalid`) guard the config itself, so `rules` and `allow` can't name them (the config is
1106
1125
  refused), and the ratchet never lowers them, nor the other rules about the config, packages or
1107
- generated files (`stale-exception`, `package-rule-override`, `package-rules-invalid`,
1126
+ generated files (`stale-exception`, `stale-extension`, `extension-added`, `package-rule-override`, `package-rules-invalid`,
1108
1127
  `package-doctor-declaration`, `plugin-error`, `build`, `agent-guide-stale`, `contracts-stale`). A
1109
1128
  shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `allow`, `rules` or
1110
1129
  `packageRules`: check out with `fetch-depth: 0` and fetch the base ref (see
@@ -1114,10 +1133,57 @@ shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `al
1114
1133
  { "doctor": { "ratchet": ["ui/lists-use-resource-view", "core/direct-data-access"] } }
1115
1134
  ```
1116
1135
 
1117
- ```bash
1118
- genesis doctor --strict --base origin/main
1136
+ ### Declared extensions
1137
+
1138
+ Genesis is a trellis, not a ceiling: a rule knows the usual ways of building on a primitive, and
1139
+ an app may build on Genesis in a way the rule doesn't recognize. A package rule that allows this
1140
+ declares its extension points (`extensible`), and an app that uses one, defensibly, declares it in
1141
+ `doctor.extend` instead of hiding the finding in `allow`:
1142
+
1143
+ ```json
1144
+ {
1145
+ "doctor": {
1146
+ "extend": [
1147
+ {
1148
+ "rule": "ui/lists-use-resource-view",
1149
+ "file": "src/routes/board.tsx",
1150
+ "buildsOn": "useBoardColumns",
1151
+ "reason": "The board groups rows by a computed lane, which the view's board block can't express yet.",
1152
+ "upstream": "https://github.com/marktiderman/genesis/issues/123"
1153
+ }
1154
+ ]
1155
+ }
1156
+ }
1119
1157
  ```
1120
1158
 
1159
+ `allow` is debt and only shrinks. An extension is a reviewed decision, and it is bounded:
1160
+
1161
+ - **By the rule.** Only package rules can be extended, and only at the points they declare
1162
+ (`ui/lists-use-resource-view`: `ResourceView.slots`, `ResourceView.renderDetail`,
1163
+ `ResourceView.toolbar`, `useResourceView`, `useResourceTable`, `useBoardColumns`;
1164
+ `ui/records-use-record-view`: `BuilderLayout`). A built-in rule (`deprecated-import`,
1165
+ `removed-scope-name`, `raw-tag`, …) or a package rule without points can't be, so debt can't be
1166
+ renamed an extension.
1167
+ - **By the file, now.** It names one file (no globs) and covers the findings of its rule that the
1168
+ file has when the extension is declared. Under `--base`, once the merge base has the extension,
1169
+ a file with more of them than at the merge base reports them all at their level, as the ratchet
1170
+ would.
1171
+ - **By review.** `allow-grew` and `rules-weakened` don't count it. Under `--base` a new one is an
1172
+ `extension-added` info, and the report's summary lists every extension the branch adds with its
1173
+ reason ("Extensions added on this branch"; `extensionsAdded` in `--json`). The pull request's
1174
+ review is where it is accepted; nothing else gates it.
1175
+
1176
+ The doctor checks each one:
1177
+
1178
+ - `reason` is required, at least six words and 40 characters: why the rule's primitive doesn't
1179
+ fit this file. `upstream` links the gap's write-up for Genesis, when it is one.
1180
+ - `extension-invalid` (error, can't be lowered or allowed): the rule declares no extension points
1181
+ or `buildsOn` isn't one of them, the file doesn't import `buildsOn` from a Genesis package or
1182
+ doesn't use it (render or call it; for `X.slots` and the like, pass that prop on `<X>`),
1183
+ `buildsOn` is what a package rule replaces (`DataTable`, `DetailPage`), or the doctor flags it in
1184
+ that file (a deprecated import). The findings it would cover stay.
1185
+ - `stale-extension` (warn): the file no longer has a finding of `rule`; remove the entry.
1186
+
1121
1187
  ### Config
1122
1188
 
1123
1189
  `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
@@ -1148,7 +1214,7 @@ genesis doctor --strict --base origin/main
1148
1214
  | `native` | | `{ routerRoot }` for the native pack. |
1149
1215
  | `supabase` | | `{ migrations, base, exposedSchemas, since, automaticBranching }` for the supabase pack. |
1150
1216
  | `src` | `["src"]` (`["app", "src", "components"]` with the native pack) | Folders (or files) to scan. |
1151
- | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | |
1217
+ | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | File extensions to scan (declared extensions are `extend`). |
1152
1218
  | `ignore` | | Globs to skip, added to the defaults. `*` stays in a folder, `**` crosses folders, a trailing `/` means the whole folder. |
1153
1219
  | `uiPackage` | `@marktiderman/genesis-ui` (`@marktiderman/genesis-ui-native` with the native pack) | |
1154
1220
  | `themeCss` | the design system's `dist/themes/*.css` + genesis-ui's styles | One stylesheet or a list: package paths (`@marktiderman/genesis-design-system/dist/themes/genesis.css`) or app paths. |
@@ -1163,7 +1229,8 @@ genesis doctor --strict --base origin/main
1163
1229
  | `packageRules` | | `{ "<package>/<rule>": { level?, files?, exclude?, reason } }` for the rules packages declare. `reason` is required. `files` and `exclude` apply to `prefer` rules; a package plugin decides its own files, so only `level` applies to its rules. See [Package rules](#package-rules). |
1164
1230
  | `ratchet` | | `true`, or a list of rule ids, ratcheted under `--base`. See [The ratchet](#the-ratchet). |
1165
1231
  | `contracts` | | `{ out?, schemas?, databaseEnv? }`: the supabase pack's `contracts-stale` check. Needs the supabase pack. |
1166
- | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
1232
+ | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. Debt: under `--base` it only shrinks. |
1233
+ | `extend` | | Declared extensions: `{ rule, file, buildsOn, reason, upstream? }`, at a package rule's declared extension points, bounded by the findings the file had when declared. See [Declared extensions](#declared-extensions). |
1167
1234
  | `patterns` | | Declarative rules, below. |
1168
1235
  | `rulesDoc` | | A markdown file of declarative rules, below. |
1169
1236
  | `plugins` | | Rule modules, below. |