@marktiderman/genesis-cli 1.8.0 → 1.10.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
@@ -336,12 +336,12 @@ Upgrading Genesis upgrades the checks.
336
336
 
337
337
  | Option | |
338
338
  | --- | --- |
339
- | `--strict` | Fail on warnings too. |
340
- | `--json` | Print `{ ok, genesis, errors, warnings, findings, unused }`. Build output is captured, not streamed. |
339
+ | `--strict` | Fail on warnings too. `info` findings never fail. |
340
+ | `--json` | Print `{ ok, genesis, errors, warnings, infos, findings, unused }`; each finding has its `level` (`error`, `warn` or `info`). Build output is captured, not streamed. |
341
341
  | `--build` | After the checks, run `doctor.build` commands, or the app's `typecheck` then `build` scripts. A build that itself runs the doctor doesn't recurse. |
342
342
  | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
343
343
  | `-d, --dir <dir>` | The app's folder (default: cwd). |
344
- | `--print-genesis` | Print the components, tokens, raw tags and palette read from Genesis, and exit. |
344
+ | `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
345
345
 
346
346
  Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built).
347
347
 
@@ -358,11 +358,57 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
358
358
  | `raw-color` | error | Hex and `rgb()/hsl()` literals in code and CSS, via the same lexer as the repo's `check:token-usage` (comments, issue refs and `hsl(var(--x))` are fine). A brand file that defines token values needs an `allow` entry. |
359
359
  | `undefined-token` | error | `var(--x)` where the theme doesn't define `--x`. Tokens declared in the app's CSS (or only `tokenFiles`) and inline style custom properties count as defined; `--tw-*` and `--radix-*` are ignored. |
360
360
  | `shadowed-export` | error | An exported value named like a Genesis export (`export function Button`). Reuse or extend it. |
361
+ | `duplicate-genesis-package` | warn | More than one copy of a `@marktiderman/genesis-*` package that the app can load, with each copy's path, version and the ranges that asked for it. Found by resolving dependencies the way Node does, from each package's real folder, so npm/yarn/bun hoisted and nested trees, pnpm's `.pnpm` store (in the app, or at the workspace root above a sub-app) and bun's isolated `.bun` store all count; a store entry nothing resolves to is ignored. Two copies are two module instances: a `DataProvider` from one is invisible to hooks from the other. A copy reached only through dev tooling (the app's `devDependencies`, or anything under `@marktiderman/genesis-cli`, wherever it's listed) is `[dev only]`: every path to it from the app runs through a declared devDependency (or the CLI). When exactly one copy is reached from a declared runtime dependency and every other copy is dev-only, the finding is `info` (it can't split the app's contexts). Anything else warns, a copy reached through an undeclared hoisted package included. An app with no runtime dependencies at all (a bundled SPA listing everything in `devDependencies`) has its devDependencies taken as runtime. |
362
+ | `peer-range-mismatch` | warn | An installed Genesis package's `peerDependencies` range on another Genesis package that the copy it resolves (looked up from its own folder, as Node does) doesn't satisfy: the package, the range and the installed version. Missing peers and non-semver ranges (`workspace:*`) are skipped. Ranges are read with npm's grammar (`^ ~ x - ||`, prereleases only when the range names one). A mismatch inside a dev-only copy (the CLI's own tree) is `info`. |
363
+ | `hand-rolled-sub-nav` | warn | A route under the layout that renders `AppShell` that switches its sections with its own page-level `<TabsList>` or `<SubNavTabs>`, when the installed Genesis has `useAppShellSubNav`. Tabs inside a card, dialog, sheet, popover, accordion, panel, table or another tab's content are fine, as are pages that call the hook. Use `useAppShellSubNav(items, { mode: "tabs" })`, `AppShellPageHeader` and `AppShellSubNavEnd` from `@marktiderman/genesis-ui/layout` ([sub-navigation](../ui/SKILL.md)). |
364
+ | `local-genesis-copy` | warn | An app component definition named like a component of `uiPackage` or of `componentPackages` (forms-studio's `ResourceHeader`, `SettingsSection`, `ResourceSettingsPage`, `HeadlineNumbers`, `SummaryCard`, `ShareDialog`, …): "Genesis already has X". A definition renders JSX, isn't in a file that imports the Genesis one, and is exported or lives outside the routes folder; a route's own non-exported functions and anything passed as `component` / `errorComponent` / `pendingComponent` / `notFoundComponent` (TanStack's `FormError`) are not copies. An exported genesis-ui value is `shadowed-export` instead; `const X = lazy(() => import("@marktiderman/genesis-…"))` is fine. |
365
+ | `resource-workspace` | info | In a routes folder where a detail page (`courses.$courseId.tsx`, `[id]/page.tsx`) renders `AppShellPageHeader`, directly or through one local import, the other detail pages there that don't: one workspace header and tab row for every resource. Reported, never failing (`--strict` included); `rules` can raise it to `warn`. |
366
+ | `page-layout` | warn | A route inside the AppShell (under the layout route that renders it) that renders no Genesis page layout (the `…Page` / `…PageShell` components `uiPackage` and `componentPackages` export, not `BreadcrumbPage`) itself, through one local import, or from a layout route around it (`my/route.tsx` supplying `DetailPage` covers `my/index.tsx`). A `…Page`, `…Screen` or `…Workspace` imported from any Genesis package counts. Routes outside the shell (sign-in, landing, public forms) aren't checked until Genesis ships layouts for them. Layout-only (`route.tsx`, `__root`, `<Outlet>`) and redirect-only routes are skipped; off with the `native` pack (see `native-screen-layout`). |
367
+ | `iso-date-slice` | warn | A day cut from an ISO timestamp: `.toISOString().slice(0, 10)`, `.substring(0, 10)`, `.substr(0, 10)`, `.split("T")[0]` or `.split("T").at(0)`. That's the day in UTC, which for an evening in the Americas is already tomorrow. Use `personDay(person)` or `dayIn(zone)` from `@marktiderman/genesis-core/dates`. Test files are skipped; where UTC is what you mean (a log name, a UTC report), allow it with a reason. |
361
368
  | `stale-exception` | warn | An `allow` entry that no longer matches anything. |
362
369
 
363
370
  It also prints **Available but unused**: the Genesis components no file imports. Check it
364
371
  before building something.
365
372
 
373
+ The route rules (`hand-rolled-sub-nav`, `resource-workspace`, `page-layout`) read the routes
374
+ folder (`routesDir`, default the first of `src/routes`, `src/app`, `app`, `src/pages`, `pages`).
375
+ **TanStack Router**: flat `a.$id.tsx` or folders, `route.tsx` layouts, `__root.tsx`, `-private`
376
+ files skipped, a trailing `_` un-nesting a segment, and `posts.lazy.tsx` paired with `posts.tsx`
377
+ as one route (findings point at the lazy file, which holds the component). **Next.js `app/`**
378
+ (chosen when the folder has `page` / `layout` files and no `__root`): `layout.tsx` around
379
+ `page.tsx`, `[id]` params, `(group)` and `@slot` folders dropped from the path; private
380
+ `_folders` and the special files (`error`, `global-error`, `loading`, `not-found`, `template`,
381
+ `default`, `route` handlers, metadata files) aren't routes. **Next.js `pages/`**: `_app` is the
382
+ layout; `_document`, `_error`, `404`, `500` and `api/` aren't pages.
383
+
384
+ A route whose component is imported (`component: CoursesPage`, `export { default } from …`)
385
+ renders; only a route that renders nothing but `<Navigate>` / `<Redirect>` / `<Outlet>` (or no
386
+ component) is redirect-only. A route is a layout when it is a layout file, a pathless `_layout`
387
+ route, or renders an `<Outlet>` itself or in the component it imports. `__root` and Next's
388
+ `layout` files are pure layouts, as is a pathless route or one whose only markup around the
389
+ `<Outlet>` is a wrapper (`<div className="space-y-4"><Outlet /></div>`); a route with content of
390
+ its own beside the outlet (text, a heading, a list or table), `posts/route.tsx` included, is a page
391
+ too, and `page-layout` and `hand-rolled-sub-nav` check it. Next's `(group)` and `@slot` folders
392
+ aren't URL segments, but a group's layout wraps only the routes in that group.
393
+
394
+ What a route renders is followed through the app's modules up to six deep: the imports of the
395
+ components it renders (or names as `component:`), `lazy(() => import(…))` /
396
+ `lazyRouteComponent(…)`, re-exports and barrels, through relative paths, tsconfig/jsconfig
397
+ `paths` and `baseUrl` (following `extends`, to a file or a package's config), package.json
398
+ `imports` and the `@/`, `~/`, `#/` defaults. Imports it only calls (data helpers, hooks) aren't
399
+ followed, and an `import(…)` inside a string or comment isn't one. An import that is neither an
400
+ app file nor an installed or declared package makes that route unsure, and the route rules don't
401
+ report it; it never makes a route a layout. Past six modules the trail stops as a one-hop check
402
+ would: the route is reported.
403
+
404
+ `hand-rolled-sub-nav` and `page-layout` are warnings (failures under `--strict`) and
405
+ `resource-workspace` is `info`. Opt out with `rules`
406
+ (`{ "page-layout": "off" }`) or a justified `allow` entry for one file:
407
+
408
+ ```json
409
+ { "rule": "hand-rolled-sub-nav", "file": "src/routes/_shell/onboarding.tsx", "reason": "A wizard's steps, not sections." }
410
+ ```
411
+
366
412
  Scanned by default: `src/**/*.{ts,tsx,js,jsx,mts,cts,css}`, skipping tests, `__fixtures__`,
367
413
  `__mocks__`, `*.d.ts` and `*.gen.*`. Comments are ignored by every rule.
368
414
 
@@ -416,6 +462,7 @@ bodies blanked, so text inside a function body never matches; the one exception
416
462
  | `migration-rls` | error | A table in an exposed schema whose row level security is off once every migration has run: never enabled, or disabled later. Renames (`alter table … rename to`, `set schema`) and drops are followed. RLS enabled by dynamic SQL (a `do $$ … execute format('alter table %I enable row level security', t) … $$` loop) can't be traced, so such a block counts as enabling it for every table created before it. |
417
463
  | `migration-definer-search-path` | error | A `security definer` function or procedure without `set search_path`. Functions are keyed by name and argument types, so overloads are separate; `alter function … security definer` makes one definer, `alter function … set search_path` fixes it, and renames, replaces and drops are followed. |
418
464
  | `migration-edited` | error | A `.sql` migration that already exists at the merge base with `supabase.base` (default `origin/main`) was modified, deleted or renamed. Applied migrations are never edited; add a new one. Skipped outside a git repo; a **warn** when the base ref isn't available. |
465
+ | `migration-testing-kit` | error | A migration that uses `genesis_testing`, genesis-supabase's pgTAP kit for test databases only (it signs in as anyone and resets roles). Keep it in `supabase/tests/database/000_genesis_testing.test.sql`. |
419
466
 
420
467
  **Which migrations are new.** In a git repo with the base ref, a migration is new when it was
421
468
  added, modified or is untracked since the merge base. `since` (a file name or timestamp prefix)
@@ -468,7 +515,9 @@ migrations never fail a build. In CI, check out with full history and fetch the
468
515
  | `rawTags` | | `{ "img": "Avatar" }` adds a mapping; `{ "select": false }` stops checking a tag. |
469
516
  | `forbiddenImports` | | `{ "<regexp>": "message" }`, added to the defaults. |
470
517
  | `localPrimitiveDirs` | `["src/components/ui"]` | |
471
- | `rules` | | `{ "<rule>": "error" \| "warn" \| "off" }` for any rule, built-in or yours. |
518
+ | `routesDir` | first of `src/routes`, `src/app`, `app`, `src/pages`, `pages` | The web routes folder the route rules read. |
519
+ | `componentPackages` | `["@marktiderman/genesis-forms-studio"]` | Genesis packages besides `uiPackage` whose components `local-genesis-copy` and `page-layout` read (skipped when not installed). `--print-genesis` lists them under `companions`. |
520
+ | `rules` | | `{ "<rule>": "error" \| "warn" \| "info" \| "off" }` for any rule, built-in or yours. `info` is reported and never fails, `--strict` included. |
472
521
  | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
473
522
  | `patterns` | | Declarative rules, below. |
474
523
  | `rulesDoc` | | A markdown file of declarative rules, below. |