@warlock.js/core 5.35.0 → 5.37.0

package/skills/upgrade-from-5-29/SKILL.md

@@ -552,3 +552,94 @@ Root components and providers execute in both realms. Move server-only work into
 one `#vessel` around `{children}`. Client navigation still swaps layout/page
 children while preserving the document root. Remove temporary explicit form IDs
 only when the application does not otherwise depend on those names.
+
+## 5.35 to 5.36 per-page API routes
+
+A page document now carries only the named API routes its client code can reach. Before 5.36 every page carried every named route, so a browser call to a name the build cannot see worked on every page by accident. Check each `apiHref()` and `useSubmitForm({ route })` call:
+
+- A name written as a string literal, a constant or a template with a static prefix is found automatically.
+- A name computed at run time, or taken from a module the build cannot follow, now throws on the page that calls it. Declare the names in that page's setup file, for example `export const config = { apiRoutes: ["orders.*"] };`, a layout or root `config` covers every page that renders it. Or call the endpoint with an explicit `path` and `method`.
+- `npx warlock check` reports the call sites that need a declaration as `WL9019`.
+
+Routes registered with `clientVisible: false` are never embedded, and a browser call to one is an error (`WL9020`). Keep endpoints the browser must not reach on that option. Authorization is unchanged: the server still decides each request.
+
+To measure a page's inline payload, set `build.budgets.payload` (default `64kb`). An over-budget route logs one line per process and never fails a request.
+
+## 5.35 to 5.36 translation payloads
+
+A page's hydration payload now carries only the translations its client code
+can reach, in route-dictionary (`locales.json`) and global-registry (`extend()`)
+apps alike. The groups every page uses (default `app` and `common`) arrive once
+per locale in a hashed, cached file that the page preloads. Nothing in a page's
+render changes: server output is the full dictionary, as before.
+
+Run `warlock build`, then `warlock check`. A `WL9104` warning marks a page that
+renders a translation key computed at runtime. Declare the keys it renders in
+the page's setup file, for example
+`export const config = { translations: ["statuses.*", "members.title"] }`, so the
+page ships only what it uses.
+
+In development, a warning names a key the page reads but its payload lacks, and
+resolves it from the full table so the page keeps working. In production the
+key renders as its own text and the miss is reported once through
+`onClientError` with `kind: "translations"`. Declare the key, or set
+`build: { translations: { prune: false } }` in the web connector options while migrating to
+restore the previous per-page payload.
+
+Global-registry apps are covered too. Their shared table is served at
+`/__warlock/translations/<locale>.<hash>.json`, which is cached immutable in
+production. A direct `trans()` call from `@mongez/localization` is not checked
+for a pruning miss; the calls through `useTrans()` are.
+
+## 5.35 to 5.36 Vite 8 and Vitest 5
+
+`@warlock.js/web` requires Vite 8 (`^8.0.0`) and `@vitejs/plugin-react` 6, and the
+test kit requires Vitest 5. Vite 8 bundles with Rolldown and transforms
+TypeScript with Oxc. Vite 7 is not supported; plugin-react 6 needs Vite 8, so the
+family moves together. Vite 8 needs Node.js 20.19 or 22.12 and newer, Vitest 5
+needs 22.12 or newer; Warlock already requires 22.15.
+
+```bash
+npx warlock upgrade --from 5.35 --to 5.36.0 --dry-run
+npx warlock upgrade --from 5.35 --to 5.36.0
+npm install
+npx warlock check
+```
+
+The `vite-8-vitest-5` codemod:
+
+- raises `vite` (8.3.3), `vitest` and `@vitest/*` (5.0.3) and `@vitejs/plugin-react`
+  (6.1.2) in `dependencies`, `devDependencies`, `overrides` and `resolutions`,
+  keeping `^`, `~` or exact style;
+- rewrites a generated `src/test-runner.ts` from `VitestTestRunner` in
+  `vitest/runners` to `TestRunner` from `vitest`, and calls
+  `this.onCleanupWorkerContext?.(cleanup)` (the hook is absent in vm pools);
+- lists, without editing, imports of the removed `vitest/coverage`,
+  `vitest/reporters`, `vitest/environments`, `vitest/snapshot`, `vitest/suite`,
+  `vitest/mocker` and `vitest/internal/module-runner` entry points, other names
+  imported from `vitest/runners`, a top-level `esbuild` option in a Vite or
+  Vitest config, and object-form `output.manualChunks`.
+
+Do these by hand when the codemod lists them:
+
+- Move a config's `esbuild: { jsx: "automatic" }` to
+  `oxc: { jsx: { runtime: "automatic" } }`. `esbuild.target` is not converted, and
+  Oxc does not lower native decorators: keep `lowerStage3Decorators()` from
+  `@warlock.js/core/vite` first in `plugins` for decorated modules, as in the
+  generated test config.
+- Replace object `manualChunks` with
+  `build.rolldownOptions.output.codeSplitting.groups`; `build.rollupOptions` still
+  works but is deprecated in favour of `build.rolldownOptions`.
+- A custom bundler `external` list that names Node builtins is still refused by the
+  client build.
+
+Vitest 5 changes defaults that can alter a green suite: `clearMocks` is true,
+`json` and `junit` reporters write to `.vitest/` instead of stdout, `-t` joins a
+test's names with `>`, `VITEST_POOL_ID` and `VITEST_WORKER_ID` start at 1, nested
+`vi.mock`/`vi.hoisted` calls throw, and an unawaited `resolves` or `rejects`
+assertion fails the test. Vitest also no longer searches parent directories for a
+config file; run it from the package that owns the config. Official guides:
+https://vite.dev/guide/migration and https://vitest.dev/guide/migration.
+
+A project that uses `@warlock.js/ai`'s custom matchers needs Vitest 5 for their
+TypeScript types.

package/skills/use-localization/SKILL.md

@@ -357,3 +357,7 @@ connectors and the file runtime's loader channel, queued work, watchers, health
 workers, and registered module cleanup hooks, including after partial startup.
 A Node loader registration is process-scoped; its message channel is closed at
 teardown. Module-owned timers/listeners must register their cleanup hooks.
+
+## Translation keys in pages (5.36)
+
+`warlock check` reports `WL9104` when a page renders a translation key computed at runtime (`trans(key)` with no static prefix, or a translator passed on as a value). Such a page ships every translation group. Declare its keys in the page's setup file, `export const config = { translations: ["statuses.*", "members.title"] }`, to ship only what it uses. The `web` skill `localize-pages` covers the browser side.

package/skills/warlock-check/SKILL.md

@@ -141,14 +141,17 @@ and work through the manual-review list. Use `--lint=oxc` for new apps.
 The following codes default to **warnings**, so upgrading does not fail existing projects.
 They parse real TypeScript/JSX syntax with the same oxc-parser adapter as the existing conventions.
 
-| Code     | Convention                                                                   | Remedy                                                                                                                                                             |
-| -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `WL9013` | A component file exceeds 150 lines                                           | Split components and extract hooks; configure `componentLineLimit`.                                                                                                |
-| `WL9014` | More than one component in a file                                            | Move each component into its own TSX file.                                                                                                                         |
-| `WL9015` | State/effects or event-handler functions inside a component                  | Move `useState`, `useReducer`, `useEffect`, `useLayoutEffect` and handlers into `use-*.ts` hooks.                                                                  |
-| `WL9016` | Native select, checkbox, radio, date, time or datetime-local input           | Use the design-system control. Native controls are allowed in `src/web/design-system/**`.                                                                          |
-| `WL9017` | DOM input/textarea/select native validation                                  | Use shared schema validation instead of `required`, `pattern`, `min`, `max`, `minLength`, `maxLength` or input `type="email"`. Custom component props are allowed. |
-| `WL9018` | Exported `RequestHandler` in `src/app/**/controllers` lacks `responseSchema` | Assign `handler.responseSchema` to document each response status.                                                                                                  |
+| Code     | Convention                                                                       | Remedy                                                                                                                                                             |
+| -------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WL9013` | A component file exceeds 150 lines                                               | Split components and extract hooks; configure `componentLineLimit`.                                                                                                |
+| `WL9014` | More than one component in a file                                                | Move each component into its own TSX file.                                                                                                                         |
+| `WL9015` | State/effects or event-handler functions inside a component                      | Move `useState`, `useReducer`, `useEffect`, `useLayoutEffect` and handlers into `use-*.ts` hooks.                                                                  |
+| `WL9016` | Native select, checkbox, radio, date, time or datetime-local input               | Use the design-system control. Native controls are allowed in `src/web/design-system/**`.                                                                          |
+| `WL9017` | DOM input/textarea/select native validation                                      | Use shared schema validation instead of `required`, `pattern`, `min`, `max`, `minLength`, `maxLength` or input `type="email"`. Custom component props are allowed. |
+| `WL9018` | Exported `RequestHandler` in `src/app/**/controllers` lacks `responseSchema`     | Assign `handler.responseSchema` to document each response status.                                                                                                  |
+| `WL9019` | Browser route call (`apiHref`, `useSubmitForm({ route })`) takes a run-time name | Pass a string literal or a template with a static prefix, or declare the names with `config.apiRoutes` in a page setup file.                                       |
+| `WL9020` | Browser code names a route registered with `clientVisible: false` (error)        | Call the endpoint from the server, or remove `clientVisible: false` from the route.                                                                                |
+| `WL9104` | Translation key computed at runtime in `src/web` (the page ships every group)    | Declare the keys with `config.translations` in the page's setup file, for example `["statuses.*"]`.                                                                |
 
 Web rules apply to `src/web/**/*.tsx`. Components are top-level JSX-returning functions
 with a capitalized name (or an anonymous default export). Hook files and ordinary helpers

package/skills/warlock-conventions/SKILL.md

@@ -186,7 +186,7 @@ router.post("/posts", createPostController, { middleware: [authMiddleware("user"
 router.post("/contact", contactController, { public: true });
 ```
 
-A route inside `guarded(() => …)` or `router.group({ middleware: [authMiddleware()] }, …)` is guarded. A middleware counts as a guard when its name contains `auth` or `guard`, or when it is a constant initialised with `markAuthGuard()` in the same file. `warlock dev` warns about the same routes at runtime.
+A route inside `guarded(() => …)` or `router.group({ middleware: [authMiddleware()] }, …)` is guarded. A middleware counts as a guard when its name contains `auth` or `guard`, or when it is a constant initialised with `markAuthGuard()` in the same file, or a local factory that returns `markAuthGuard(fn)` and is called in the `middleware` list. `warlock dev` warns about the same routes at runtime.
 
 ### `WL9007` — safe redirects