@marktiderman/genesis-cli 1.11.3 → 1.12.1

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
@@ -135,6 +135,29 @@ no backslashes, and a file that resolves (through a symlink) outside its package
135
135
  runtime block is made by a function (`createPush`) keeps a test that its manifest says what the
136
136
  block declares.
137
137
 
138
+ ### Local packages
139
+
140
+ An app's own workspace packages can be Genesis-style packages too. List them in
141
+ `genesis.config.json`, as app-relative folders or folders ending in `/*`:
142
+
143
+ ```json
144
+ { "localPackages": ["packages/*"] }
145
+ ```
146
+
147
+ A local package declares blocks the way a Genesis package does:
148
+ - a `genesis.blocks` manifest in its package.json and a `./blocks` export;
149
+ - its own `migrations/NNNN_name.sql`, each with a pgTAP test.
150
+
151
+ Then:
152
+ - `genesis add <block>` and `genesis migrate` copy its migrations and tests like any package's,
153
+ with a `genesis-migration` header naming the local package. Nothing is installed: it lives in
154
+ the app's repo.
155
+ - `genesis doctor` scans its source with every rule, and the [`packages` pack](#rule-packs)
156
+ holds it to a package's standard: no app imports, declared dependencies, tested and never-edited
157
+ migrations, registered in `features.ts`, and a changeset or version bump with every change.
158
+ - A local package keeps package shape, so publishing it later (GitHub Packages or npm) needs no
159
+ restructuring.
160
+
138
161
  ### genesis add
139
162
 
140
163
  `genesis add <block>` plans, prints the plan, asks (or `--yes`), then:
@@ -416,7 +439,7 @@ Scanned by default: `src/**/*.{ts,tsx,js,jsx,mts,cts,css}`, skipping tests, `__f
416
439
 
417
440
  ### Rule packs
418
441
 
419
- Two packs are opt-in, so a web app is unaffected until it lists them. Turn them on explicitly
442
+ Three packs are opt-in, so a web app is unaffected until it lists them. Turn them on explicitly
420
443
  (they are not auto-detected, so adding `expo` or a `supabase/` folder never changes a build's
421
444
  result on its own):
422
445
 
@@ -479,6 +502,39 @@ migrations never fail a build. In CI, check out with full history and fetch the
479
502
  - run: git fetch origin main
480
503
  ```
481
504
 
505
+ **`packages`**, for the app's [local packages](#local-packages). Each one is held to a
506
+ Genesis package's standard. The change rules compare against a base ref, given as
507
+ `genesis doctor --base origin/main` (or `doctor.packages.base`). Without one, or when git
508
+ can't compare, they report a single info finding ("change gate skipped") and never fail:
509
+
510
+ ```json
511
+ { "localPackages": ["packages/*"], "doctor": { "packs": ["packages"] } }
512
+ ```
513
+
514
+ ```bash
515
+ genesis doctor --strict --base origin/main
516
+ ```
517
+
518
+ A file whose literals can't be parsed for sure is skipped, and type-only imports never count
519
+ as dependencies.
520
+
521
+ | Rule | Level | What it flags |
522
+ | --- | --- | --- |
523
+ | `package-app-import` | error | A package importing the app's own code: `@/…`, `~/…`, a relative path that leaves the package, or an alias (the package's own tsconfig `paths`) that points outside it. package.json `#imports` and aliases that stay inside the package are its own files. |
524
+ | `package-undeclared-dependency` | error | A bare import whose package isn't in the package's `dependencies`, `peerDependencies`, `devDependencies` or `optionalDependencies` (`workspace:` ranges count). Node built-ins and type-only imports (multi-line too) are fine. |
525
+ | `package-export-missing` | error | An `exports` target that doesn't exist. Build output (`./dist/…`, `./build/…`) and patterns are left alone. |
526
+ | `package-block-invalid` | error | A `genesis.blocks` declaration that isn't a valid block manifest. |
527
+ | `package-migration-test` | error | A migration without a pgTAP test: a block migration with no `test` (or a missing one), or any `migrations/NNNN_name.sql` without `migrations/tests/NNNN_name.test.sql`. |
528
+ | `package-migration-number` | error | Two migrations in one package with the same `NNNN_` number. |
529
+ | `package-untagged-tests` | warn | A package whose tests name no feature (`@feat:<id>`). |
530
+ | `package-unregistered` | warn | No feature in `features.json` lists the package's folder in `links.code`. |
531
+ | `package-migration-edited` | warn | With a base ref: a package migration that existed at the merge base and was changed, deleted or renamed. |
532
+ | `package-unversioned-change` | warn | With a base ref: files in the package changed but neither a higher `version` nor a new changeset naming it in its front matter did; a changeset without a `Features:` line; or blocks or exports changed without a change to `features.ts`. Run CI with `--strict` so these fail. |
533
+
534
+ Symlinks inside a package aren't followed, and a `packages/*` folder without a usable package.json (or a name) is skipped. `localPackages` entries may climb out of the app (`../../packages/*`) as long as they stay in its repository.
535
+
536
+ Every other rule also scans local packages' source, as it does the app's.
537
+
482
538
  ### Config
483
539
 
484
540
  `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):