@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 +81 -14
- package/dist/cli.js +387 -41
- package/dist/cli.js.map +1 -1
- package/dist/{config-DRHg7V3Z.d.ts → config-CR4kqSCp.d.ts} +48 -6
- package/dist/doctor.d.ts +34 -4
- package/dist/doctor.js +367 -37
- package/dist/doctor.js.map +1 -1
- package/dist/expo.d.ts +2 -2
- package/dist/expo.js.map +1 -1
- package/dist/genesis-catalog.json +9 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +364 -35
- package/dist/index.js.map +1 -1
- package/dist/vite.js +365 -36
- package/dist/vite.js.map +1 -1
- package/package.json +2 -2
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
|
|
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
|
|
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.
|
|
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
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
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
|
-
|
|
1118
|
-
|
|
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. |
|