@krizaka/config 0.8.1 → 0.9.0

package/README.md

@@ -5,7 +5,7 @@ rules, the three stack rules, no locale ternary), the dependency-cruiser boundar
 EditorConfig — and `krizaka-ratchet`, the counter that keeps the UI and stack debts from coming back.
 
 [![npm](https://img.shields.io/npm/v/@krizaka/config?color=3b82f6&label=npm)](https://www.npmjs.com/package/@krizaka/config)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/krizaka/krizaka-ts/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](../../LICENSE)
 
 ## Adopt it in three lines
 
@@ -24,7 +24,7 @@ export default [...krizakaNext, ...krizakaUi(), ...krizakaStack(), ...noLocaleTe
 ```
 
 ```js
-// .dependency-cruiser.cjs — « Krizaka first », cycles, unresolvable imports, dev dependencies, plus the app's own rules
+// .dependency-cruiser.cjs — the TanStack boundary, plus the app's own rules
 module.exports = { extends: "@krizaka/config/dependency-cruiser", forbidden: [] };
 ```
 
@@ -51,9 +51,7 @@ the package.
 | `@krizaka/config/eslint/ui-warnings` | `krizakaUiWarnings(options?)`: the same two debts as named plugin rules, as warnings — `krizaka/no-light-variant` (no `light:`: tokens do the theming) and `krizaka/no-raw-palette` (no `bg-zinc-900`, `text-violet-400`: a role; `allow` families). `krizaka-ratchet` counts them (`light`, `palette`), so a product adopts them now and brings the counts to 0. |
 | `@krizaka/config/eslint/stack` | `krizakaStack(options?)`: the three stack rules below (warnings). Also `STACK_RULES`. |
 | `@krizaka/config/eslint/plugin` | `krizakaPlugin`: the `krizaka` plugin carrying every rule, for a hand-written config. |
-| `@krizaka/config/dependency-cruiser` | The shared dependency-cruiser config, generated from the covered-domains map: one `krizaka-first-<domain>` rule per domain (dates, i18n, query, icons, ui), `no-circular`, `not-to-unresolvable`, `not-to-dev-dep`. `.withOptions({ exemptFrom })` for a monorepo whose own packages are the facades. |
-| `@krizaka/config/covered-domains` · `/covered-domains.json` | The covered-domains map (one data file) and its helpers: the message, the patterns, the Markdown table of « Use Krizaka first ». |
-| `krizaka-known-violations` (bin) · `@krizaka/config/known-violations` | The known violations of dependency-cruiser, which only shrink, see below. |
+| `@krizaka/config/dependency-cruiser` | The shared dependency-cruiser config: `krizaka-no-direct-tanstack` (no `@tanstack/*` from an app). |
 | `@krizaka/config/tsconfig/*.json` | `base` (strict, ES2022, bundler resolution), `react-library` (+ DOM, `react-jsx`), `next` (+ the Next plugin, `noEmit`, `incremental`), `react-native` (`jsx: react-native`, `customConditions`; with Expo: `"extends": ["expo/tsconfig.base", "@krizaka/config/tsconfig/react-native.json"]`). |
 | `@krizaka/config/prettier` · `.editorconfig` | The formatting. |
 | `krizaka-ratchet` (bin) | The debt counter, see below. |
@@ -83,15 +81,30 @@ Flat config replaces a rule's options instead of concatenating them: a repositor
 `no-restricted-syntax` merges both lists with `krizakaUiRestrictedSyntax()`. `no-locale-ternary` is a plugin rule for
 that reason — it composes with anything.
 
-### The stack rules
+### The effect rules (react-effects)
 
-From [ADR-001](https://github.com/krizaka/krizaka-ui/blob/main/docs/adr/ADR-001-tanstack-under-krizaka-facades.md) — the TanStack engines run headless, behind
+[`useEffect` is for the outside world](https://github.com/krizaka/.github/blob/main/docs/standards/react-effects.md)
+(Oussama, 2026-10-27). Two rules of `krizakaStack()`, **errors by default** (`effects: "error"`); a repository with debt
+passes `effects: "warn"` while `krizaka-ratchet` (`asyncInEffect`, `derivedStateInEffect`) brings the count to 0. They
+read any file (a Vite/Tauri app has no `"use client"`).
+
+1. **`krizaka/no-async-in-effect`** — an effect that awaits, calls `.then(`, `fetch(`, `invoke(`, `api.*` or `*Client.*`:
+   read with `useQuery`, write with `useMutation` (`@krizaka/query`), keyed by the selection. A subscribe-and-cleanup
+   effect (`listen(`, `addEventListener(`, `subscribe(`, `WebSocket`… plus a `return`) is never reported.
+2. **`krizaka/no-derived-state-in-effect`** — an effect whose only statements are `setX(…)` calls: compute the value
+   during render, or reset the component with a `key`.
+
+### The three stack rules
+
+From [ADR-001](../../docs/adr/ADR-001-tanstack-under-krizaka-facades.md) — the TanStack engines run headless, behind
 `@krizaka/*` facades; a product never imports them. Warnings: `krizaka-ratchet` counts the same patterns, so an app
 adopts them before it is clean and brings each count to 0 by the end of its adoption.
 
 1. **`krizaka/no-fetch-in-client-effect`** — a `fetch` / `krizakaFetch` inside a `useEffect` (or `useLayoutEffect`)
    of a `"use client"` file: render the first screen in a Server Component, read the rest with `@krizaka/query`.
-2. **`krizaka/no-local-table-or-form`** — a `<table>`, or a `<form>` of more than one field (native fields and the field
+2. **`krizaka/no-direct-tanstack-import`** — an import of `@tanstack/*` (static, dynamic, `require`, re-export): use
+   the facade (`@krizaka/query`, `@krizaka/ui/data-table`, `@krizaka/ui/form`, `@krizaka/ui/virtual`, `@krizaka/pacer`).
+3. **`krizaka/no-local-table-or-form`** — a `<table>`, or a `<form>` of more than one field (native fields and the field
    primitives of `@krizaka/ui`; a hidden or submit `<input>` is not a field): use `DataTable` and `createKrizakaForm`.
    A search box or a one-field newsletter stays a plain form.
 
@@ -104,55 +117,8 @@ krizakaStack({
 });
 ```
 
-### « Krizaka first » — the refused imports (dependency-cruiser)
-
-Part of the stack ADR and of krizaka-ui#609, in **one tool**: dependency-cruiser carries every refused import (an import
-is an edge: it catches re-exports and dynamic imports, and the same file holds the layers); ESLint keeps the framework
-rules above. The ESLint rule `krizaka/no-direct-tanstack-import` is retired: `@tanstack/*` is `krizaka-first-query`.
-
-The **covered-domains map** is `covered-domains.json`, the single source. Each domain names its Krizaka home and what is
-refused in an app; the preset generates `krizaka-first-<domain>` from it, and the page « Use Krizaka first » of
-ui.krizaka.com is laid out from it (`coveredDomainsMarkdown()`).
-
-| Domain | Krizaka home | Refused in an app | Rule |
-| :-- | :-- | :-- | :-- |
-| Dates, times, local days | `@krizaka/intl` (formatting, `localDay`), `@krizaka/time` (arithmetic; a facade created on the first real need, krizaka-ts#76) | `date-fns*`, `@date-fns/*`, `dayjs`, `luxon`, `moment`, `moment-timezone` | `krizaka-first-dates` |
-| Words, languages | `@krizaka/i18n` | `i18next*`, `react-i18next`, `next-intl`, `next-i18next`, `react-intl`, `@formatjs/*`, `@lingui/*`, `i18n-js`, `typesafe-i18n` | `krizaka-first-i18n` |
-| Data fetching, cache, tables, forms, virtual lists | `@krizaka/query`, `@krizaka/ui`, `@krizaka/pacer` | `@tanstack/*` | `krizaka-first-query` |
-| Icons | `@krizaka/icons` | `lucide-react`, `react-icons`, `@heroicons/*` | `krizaka-first-icons` |
-| Interface primitives | `@krizaka/ui` | `@radix-ui/*`, `radix-ui` | `krizaka-first-ui` |
-
-An entry is a package (`dayjs`, and its subpaths), a prefix (`date-fns*`) or a scope (`@tanstack/*`). It matches the
-resolved file and the module as written when it cannot be resolved (a package the app does not declare), never a local
-folder of the same name. **A Krizaka package is exempt: it is the facade.** In an app that is the packages in
-`node_modules`; in a monorepo that holds its own Krizaka packages, say where they live:
-
-```js
-// .dependency-cruiser.cjs of a monorepo (krizaka-ui, krizaka-ts)
-module.exports = require("@krizaka/config/dependency-cruiser").withOptions({ exemptFrom: ["(^|/)packages/"] });
-```
-
-Every message names the home and ends « Missing function? add it to the package first. » — a missing function is added
-to the Krizaka package, never worked around with the library. Run it with `depcruise --output-type err-long <folders>`
-to read the message (`err` prints the rule name only). Beside the domains, the preset owes every repository
-`no-circular`, `not-to-unresolvable` (declare the dependency, or fix the path; set `options.tsConfig` for path aliases)
-and `not-to-dev-dep` (tests, stories, scripts and tool configs may import devDependencies; a package that is also a `peerDependency` is installed by the consumer, so production code may import it). Run `depcruise` from the
-workspace that owns the `package.json`.
-
-#### Known violations (they only shrink)
-
-An app that adopts the rules late records what it already breaks, and the debt only goes down:
-
-```bash
-krizaka-known-violations init src app         # once, in the adoption pull request: writes .dependency-cruiser-known-violations.json
-depcruise src app --config .dependency-cruiser.cjs --ignore-known .dependency-cruiser-known-violations.json   # lint: new violations fail
-krizaka-known-violations check src app        # lint: also fails on a recorded violation that is fixed ("lock the gain")
-krizaka-known-violations update src app       # removes the fixed ones; NEVER adds one, and fails while a new one exists
-```
-
-The file is the format of `depcruise-baseline`, so `--ignore-known` reads it. `init` refuses to overwrite it; there is
-no command that records a new violation. It replaces the `directTanstackImport` counter of `krizaka-ratchet`, which
-stays only for repositories that have not moved yet.
+The dependency-cruiser config forbids `@tanstack/*` from an app's own files, resolved or not (a package installed
+only as a dependency of a facade is caught too), and allows it from `node_modules/@krizaka/*`.
 
 `noLocaleTernary({ files, routing })`: `routing` lists the files allowed to compare locales (default: `proxy.ts`,
 `middleware.ts`, `i18n.ts`, `seo.ts`, `app/[locale]/layout.tsx`, `I18nProvider.tsx`).
@@ -195,6 +161,8 @@ npx krizaka-ratchet --json      # in CI: the same check, machine-readable
 | `arbitraryVar` | `\[var\(--` |
 | `classNameTemplate` | `` className=\{\s*` `` |
 | `fetchInClientEffect` | in a file opening with `"use client"`: `fetch(` / `krizakaFetch(` between the parentheses of a `useEffect(` / `useLayoutEffect(` |
+| `asyncInEffect` | an effect (`useEffect(` / `useLayoutEffect(`, any file) whose callback awaits or calls `.then(`, `fetch(`, `invoke(`, `api.*`, `*Client.*`, and is not a subscribe-and-cleanup |
+| `derivedStateInEffect` | an effect whose only statements are `setX(…)` calls (optionally under `if`) |
 | `directTanstackImport` | `from` / `import` / `import(` / `require(` of `"@tanstack/…"` |
 | `localTableOrForm` | `<table`, and `<form` … `</form>` holding more fields than `maxFormFields` (default 1) |
 | `retiredImport` | an import of a dependency listed in `retire` (e.g. `["framer-motion"]`): the way out of a dependency |
@@ -231,4 +199,9 @@ The CI step, after the install:
 
 ## License
 
-[Apache-2.0](https://github.com/krizaka/krizaka-ts/blob/main/LICENSE)
+[Apache-2.0](../../LICENSE)
+
+## Page templates and the account baseline
+
+- **`krizaka/page-template`** (in `krizakaStack`, a warning counted by `krizaka-ratchet` as `pageTemplate`): every page of the App Router declares the Krizaka UI template it composes, as a comment at the top of `page.tsx` (`// @template: app-settings`). The templates are `PAGE_TEMPLATES` (the site's, `app-dashboard`, `app-list-detail`, `app-settings`, `app-onboarding`, `app-empty-first-run`, `app-wizard`, `redirect`). A page that fits none says why: `// @template: custom: <reason>`.
+- **`@krizaka/config/conformance/account-baseline`**: the account baseline every app owes (profile with avatar, name and verified e-mail; preferences; security; billing where the product sells; notifications where it sends; my data). `checkAccountBaseline({ routes, features, visit })` returns the problems — each section owes controls (an avatar picker or an upload, a name field, a password field or a session button, a portal link, a switch per message kind, an export and a deletion), so a heading-only placeholder fails; `playwrightVisit(page, base)` is the `visit` of a signed-in Playwright page, counting the roles plus password and file inputs. Run it in each app's CI.

package/bin/krizaka-ratchet.mjs

@@ -8,7 +8,7 @@ const USAGE = `Usage: krizaka-ratchet [globs…] [--init | --update] [--json] [-
 
 Counts the UI debts — raw palette colours, light: variants, [var(--…)] utilities, className template strings — in the
 source files (default: app/**/*.tsx components/**/*.tsx src/**/*.tsx), and the stack debts — fetch in a client effect,
-direct @tanstack/* imports, hand-written tables and forms, imports of the dependencies listed in "retire" — in every
+data loaded in an effect, state derived in an effect, direct @tanstack/* imports, hand-written tables and forms, imports of the dependencies listed in "retire" — in every
 source file of app, components, src, lib, hooks and features; compares them with lint-ratchet.json.
 
   (no flag)  fail (exit 1) when a counter is above its recorded value
@@ -24,10 +24,13 @@ const LABELS = {
   arbitraryVar: "[var(--…)] utilities",
   classNameTemplate: "className template strings",
   fetchInClientEffect: "fetch in a client effect",
+  asyncInEffect: "data loaded in an effect (useQuery instead)",
+  derivedStateInEffect: "state derived in an effect (render instead)",
   directTanstackImport: "direct @tanstack/* imports",
   localTableOrForm: "hand-written tables / forms",
   retiredImport: "imports of retired deps",
   routeStateSelection: "selections in local state (not the URL)",
+  pageTemplate: "pages with no template declared",
 };
 
 let args;

package/conformance/account-baseline.js

@@ -0,0 +1,116 @@
+// The account baseline every Krizaka app owes (Oussama, 2026-10-22: « Avatar, etc. Ça doit être systématique »): the same
+// sections, from the `app-settings` template and the account-settings blocks of @krizaka/ui, on web and native. An app runs
+// `checkAccountBaseline` in its CI, signed in as a persona; it fails when a section is missing or renders empty.
+
+/** The sections of the account area. */
+export const AccountSection = Object.freeze({
+  Profile: "profile",
+  Preferences: "preferences",
+  Security: "security",
+  Billing: "billing",
+  Notifications: "notifications",
+  Data: "data",
+});
+
+/**
+ * The controls a visit observes on a page, by what they let a person do. `password` and `file` are counted apart: a
+ * password field has no `textbox` role, and an upload is a file input, not a radiogroup.
+ * @typedef {"radiogroup" | "textbox" | "password" | "file" | "switch" | "checkbox" | "button" | "link"} Control
+ */
+
+/**
+ * What each section owes, and when. `needs` is the product feature that makes it required (a product that does not sell has
+ * no billing section; one that sends nothing has no notifications). `owes` lists what must be there, each item a set of
+ * alternatives (`[{ radiogroup: 1 }, { file: 1 }]`: an avatar picker or an upload): a heading alone never passes.
+ * @type {readonly { id: string, needs: "billing" | "notifications" | null, owes: readonly { what: string, anyOf: readonly Partial<Record<Control, number>>[] }[], why: string }[]}
+ */
+export const ACCOUNT_BASELINE = Object.freeze([
+  {
+    id: AccountSection.Profile,
+    needs: null,
+    owes: [
+      { what: "an avatar (a picker or an upload)", anyOf: [{ radiogroup: 1 }, { file: 1 }] },
+      { what: "a display name field", anyOf: [{ textbox: 1 }] },
+    ],
+    why: "avatar (a picker, or an upload), display name, e-mail with its verified status",
+  },
+  { id: AccountSection.Preferences, needs: null, owes: [{ what: "a language or theme choice", anyOf: [{ radiogroup: 1 }] }], why: "language and theme" },
+  {
+    id: AccountSection.Security,
+    needs: null,
+    owes: [{ what: "a password change or the active sessions", anyOf: [{ password: 1 }, { button: 1 }] }],
+    why: "password change, active sessions",
+  },
+  { id: AccountSection.Billing, needs: "billing", owes: [{ what: "the way to the billing portal", anyOf: [{ link: 1 }, { button: 1 }] }], why: "the subscription and the billing portal, where the product sells" },
+  {
+    id: AccountSection.Notifications,
+    needs: "notifications",
+    owes: [{ what: "a setting per kind of message", anyOf: [{ switch: 1 }, { checkbox: 1 }] }],
+    why: "what the product sends, where it sends anything",
+  },
+  {
+    id: AccountSection.Data,
+    needs: null,
+    owes: [{ what: "an export and an account deletion", anyOf: [{ button: 2 }, { button: 1, link: 1 }, { link: 2 }] }],
+    why: "my data: export, and account deletion with confirmation (Loi 25)",
+  },
+]);
+
+/**
+ * @typedef {object} Visited what a visit of one section found
+ * @property {number} status the HTTP status after redirects
+ * @property {readonly string[]} headings the text of the page's headings
+ * @property {Partial<Record<Control, number>>} controls how many of each control the page shows (a missing one is 0)
+ */
+
+/** @param {Partial<Record<string, number>>} controls @param {Partial<Record<string, number>>} wanted */
+const meets = (controls, wanted) => Object.entries(wanted).every(([control, count]) => (controls[control] ?? 0) >= (count ?? 0));
+
+/** @param {Partial<Record<string, number>>} wanted */
+const spell = (wanted) => Object.entries(wanted).map(([control, count]) => `${count} ${control}`).join(" + ");
+
+/**
+ * Checks the account baseline of an app.
+ * @param {{ routes: Partial<Record<string, string>>, features?: { billing?: boolean, notifications?: boolean }, visit: (path: string) => Promise<Visited> }} options
+ *   `routes`: the route of each section; `visit`: signs in as a persona and opens a route (a Playwright page, or a fetch of the rendered HTML).
+ * @returns {Promise<string[]>} one line per problem; empty when the app conforms
+ */
+export async function checkAccountBaseline({ routes, features = {}, visit }) {
+  /** @type {string[]} */
+  const problems = [];
+  for (const section of ACCOUNT_BASELINE) {
+    if (section.needs && !features[section.needs]) continue;
+    const path = routes[section.id];
+    if (!path) {
+      problems.push(`${section.id}: no route (${section.why})`);
+      continue;
+    }
+    const page = await visit(path);
+    if (page.status !== 200) problems.push(`${section.id} ${path}: answers ${page.status}`);
+    else if (page.headings.length === 0) problems.push(`${section.id} ${path}: renders no heading`);
+    else
+      for (const item of section.owes)
+        if (!item.anyOf.some((wanted) => meets(page.controls, wanted)))
+          problems.push(`${section.id} ${path}: needs ${item.what} (${item.anyOf.map(spell).join(" or ")})`);
+  }
+  return problems;
+}
+
+/**
+ * The `visit` of a Playwright page: opens `base + path` and reads the headings and the controls.
+ * @param {any} page a Playwright page, already signed in as the persona
+ * @param {string} base
+ * @returns {(path: string) => Promise<Visited>}
+ */
+export function playwrightVisit(page, base) {
+  return async (path) => {
+    const response = await page.goto(`${base.replace(/\/$/, "")}${path}`, { waitUntil: "networkidle" });
+    /** @type {Partial<Record<Control, number>>} */
+    const controls = {};
+    for (const role of /** @type {const} */ (["radiogroup", "textbox", "switch", "checkbox", "button", "link"])) controls[role] = await page.getByRole(role).count();
+    // No implicit role: a password field is not a textbox, a file input is a (hidden) input behind its button.
+    controls.password = await page.locator('input[type="password"]').count();
+    controls.file = await page.locator('input[type="file"]').count();
+    return { status: response?.status() ?? 0, headings: await page.getByRole("heading").allInnerTexts(), controls };
+  };
+}

package/dependency-cruiser.cjs

@@ -1,79 +1,31 @@
-// The shared dependency-cruiser rules of a Krizaka app (the stack ADR, decision S11; « Krizaka first », krizaka-ui#609 and
-// #612). dependency-cruiser carries the IMPORT rules of the family, ESLint the framework ones (krizaka/.github
-// docs/quality-controls.md §4, §7). An app extends it and adds its own:
+// The shared dependency-cruiser rules of a Krizaka app (the stack ADR, decision S11). An app extends it and adds its own:
 //
 //   // .dependency-cruiser.cjs
 //   module.exports = { extends: "@krizaka/config/dependency-cruiser", forbidden: [/* the app's rules */] };
 //
 // dependency-cruiser concatenates `forbidden` and merges `options`. CommonJS: dependency-cruiser requires its configs.
-//
-// - `krizaka-first-<domain>`: one rule per domain of covered-domains.json (dates, i18n, query, icons, ui): an app never
-//   imports the library a Krizaka package owns; the message names the Krizaka home. A Krizaka package in node_modules is
-//   the facade and is never checked. A monorepo whose own packages are the facades says where they live:
-//   `require("@krizaka/config/dependency-cruiser").withOptions({ exemptFrom: ["(^|/)packages/"] })`.
-// - `no-circular`, `not-to-unresolvable`, `not-to-dev-dep`: the three every repository owes.
-// - The known violations of an app that adopts the rules late: see README, « Known violations » (krizaka-known-violations).
-
-const { coveredDomains, domainMessage, domainPattern, ruleName } = require("./covered-domains.cjs");
-
-const NODE_MODULES = "(^|/)node_modules/";
-/** Files that may import a dev dependency: tests, stories, scripts and the tools' own configuration. */
-const DEV_FILES =
-  "(^|/)(tests?|__tests__|__mocks__|e2e|scripts|\\.storybook|stories)/|[.](spec|test|stories|config)[.](js|mjs|cjs|jsx|ts|mts|cts|tsx)$|(^|/)\\.[^/]+rc[.](js|cjs|mjs|ts)$|(^|/)\\.dependency-cruiser[.]cjs$";
 
-/**
- * The preset, for an app whose own sources are everything outside node_modules.
- * @param {{ exemptFrom?: string[] }} [options] `exemptFrom`: path patterns of the Krizaka packages that live in this repository
- *   (they are the facades: they wrap the library, so they may import it).
- * @returns {{ forbidden: Record<string, unknown>[], options: Record<string, unknown> }} an `IConfiguration` of dependency-cruiser
- */
-function createConfig({ exemptFrom = [] } = {}) {
-  const exempt = [NODE_MODULES, ...exemptFrom];
-  return {
-    forbidden: [
-      ...coveredDomains.map((domain) => ({
-        name: ruleName(domain),
-        severity: "error",
-        comment: domainMessage(domain),
-        // the app's own sources; the @krizaka/* packages in node_modules are where the library belongs
-        from: { pathNot: exempt },
-        // resolved (node_modules/…) or not (a package the app does not declare)
-        to: { path: domainPattern(domain) },
-      })),
-      {
-        name: "no-circular",
-        severity: "error",
-        comment: "A cycle makes the order of loading a matter of luck and blocks tree shaking: move what both sides need to a third module.",
-        from: {},
-        to: { circular: true },
-      },
-      {
-        name: "not-to-unresolvable",
-        severity: "error",
-        comment: "The import points to nothing: a missing file, a missing dependency or a ghost dependency that only works by hoisting. Declare it in package.json or fix the path.",
-        from: {},
-        to: { couldNotResolve: true },
-      },
-      {
-        name: "not-to-dev-dep",
-        severity: "error",
-        comment: "Production code imports a devDependency: it is not installed in production. Move the package to `dependencies` (or `peerDependencies`, for a library whose consumer installs it), or the import to a test.",
-        from: { pathNot: [NODE_MODULES, DEV_FILES] },
-        // a package that is also a peer dependency (the library declares it for its consumer, and keeps a copy to test with) is installed where it is used
-        to: { dependencyTypes: ["npm-dev"], dependencyTypesNot: ["type-only", "npm-peer"], pathNot: ["node_modules/@types/"] },
-      },
-    ],
-    options: {
-      doNotFollow: { path: NODE_MODULES },
-      tsPreCompilationDeps: true,
-      enhancedResolveOptions: {
-        exportsFields: ["exports"],
-        conditionNames: ["import", "require", "node", "default"],
-      },
+/** @type {import("dependency-cruiser").IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "krizaka-no-direct-tanstack",
+      severity: "error",
+      comment:
+        "@tanstack/* enters an app only through its @krizaka facade (@krizaka/query, @krizaka/ui/data-table, @krizaka/ui/form, " +
+        "@krizaka/ui/virtual, @krizaka/pacer…): the facade's version is the contract, a TanStack break is fixed in one place.",
+      // the app's own sources; the @krizaka/* packages in node_modules are where TanStack belongs
+      from: { pathNot: "(^|/)node_modules/" },
+      // resolved (node_modules/…/@tanstack/…) or not (a transitive package the app does not declare)
+      to: { path: "(^|/)@tanstack/" },
     },
-  };
-}
-
-module.exports = createConfig();
-// not enumerable: dependency-cruiser validates the keys of the configuration it loads
-Object.defineProperty(module.exports, "withOptions", { value: createConfig, enumerable: false });
+  ],
+  options: {
+    doNotFollow: { path: "(^|/)node_modules/" },
+    tsPreCompilationDeps: true,
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default"],
+    },
+  },
+};

package/eslint/plugin.js

@@ -1,6 +1,6 @@
 // The `krizaka` ESLint plugin: one object carrying every rule, so that configs registering it compose (flat config
 // refuses two different objects under the same plugin name).
-import { envName, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
+import { envName, noAsyncInEffect, noDerivedStateInEffect, noDirectTanstackImport, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,pageTemplate, routeStateSelection } from "./rules.js";
 
 /** @type {import("eslint").ESLint.Plugin} */
 export const krizakaPlugin = {
@@ -8,12 +8,16 @@ export const krizakaPlugin = {
   rules: {
     "no-locale-ternary": noLocaleTernaryRule,
     "no-fetch-in-client-effect": noFetchInClientEffect,
+    "no-async-in-effect": noAsyncInEffect,
+    "no-derived-state-in-effect": noDerivedStateInEffect,
+    "no-direct-tanstack-import": noDirectTanstackImport,
     "no-local-table-or-form": noLocalTableOrForm,
     "no-light-variant": noLightVariant,
     "no-raw-palette": noRawPalette,
     "env-name": envName,
     "no-family-switcher": noFamilySwitcher,
     "route-state-selection": routeStateSelection,
+    "page-template": pageTemplate,
   },
 };
 

package/eslint/rules.js

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { countFormFields, EFFECT_NAMES_SOURCE, FETCH_NAMES_SOURCE, isLocalSelection, LIGHT_VARIANT_SOURCE, paletteSource } from "../patterns.js";
+import { countFormFields, EFFECT_NAMES_SOURCE, effectProblem, FETCH_NAMES_SOURCE, isLocalSelection, isPageFile, LIGHT_VARIANT_SOURCE, PAGE_TEMPLATES, pageTemplateProblem, paletteSource, TANSTACK_SCOPE } from "../patterns.js";
 
 /** @typedef {import("eslint").Rule.RuleModule} RuleModule */
 /** @typedef {import("estree").Node} Node */
@@ -70,6 +70,82 @@ export const noFetchInClientEffect = {
   },
 };
 
+/**
+ * Reports the effects (`useEffect` / `useLayoutEffect`) whose callback `effectProblem` says is `kind`.
+ * @param {import("eslint").Rule.RuleContext} context
+ * @param {"async" | "derived"} kind
+ * @param {string} messageId
+ */
+function effectVisitor(context, kind, messageId) {
+  return {
+    [`CallExpression${callee(EFFECT_NAMES_SOURCE)}`]: (/** @type {import("estree").CallExpression} */ node) => {
+      const fn = node.arguments[0];
+      if (fn?.type !== "ArrowFunctionExpression" && fn?.type !== "FunctionExpression") return;
+      if (effectProblem(context.sourceCode.getText(fn.body)) === kind) context.report({ node, messageId });
+    },
+  };
+}
+
+/** Oussama, 2026-10-27: async data is `useQuery` / `useMutation`, never an effect (standard: react-effects). */
+/** @type {RuleModule} */
+export const noAsyncInEffect = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid loading data (await, .then, fetch, invoke, api.*, *Client.*) in a useEffect that is not a subscription." },
+    schema: [],
+    messages: {
+      asyncInEffect:
+        "Data is not loaded in an effect: read it with useQuery and write it with useMutation (@krizaka/query), keyed by the selection so a stale answer is dropped. An effect is for a subscription (with its cleanup) or an object URL. See krizaka/.github docs/standards/react-effects.md.",
+    },
+  },
+  create: (context) => effectVisitor(context, "async", "asyncInEffect"),
+};
+
+/** Oussama, 2026-10-27: syncing React state is computed in render, never an effect (standard: react-effects). */
+/** @type {RuleModule} */
+export const noDerivedStateInEffect = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid a useEffect whose only statements are setState calls (derive the value in render, or reset with a key)." },
+    schema: [],
+    messages: {
+      derivedState:
+        "An effect that only sets state from props or state renders twice: compute the value during render, or reset the component with a `key`. See krizaka/.github docs/standards/react-effects.md.",
+    },
+  },
+  create: (context) => effectVisitor(context, "derived", "derivedState"),
+};
+
+/** S11: `@tanstack/*` is imported by the `@krizaka/*` packages only — the version is the contract. */
+/** @type {RuleModule} */
+export const noDirectTanstackImport = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid importing @tanstack/* outside the @krizaka/* packages." },
+    schema: [],
+    messages: {
+      tanstack:
+        "{{source}} is imported through its @krizaka facade (@krizaka/query, @krizaka/ui/data-table, @krizaka/ui/form, @krizaka/ui/virtual, @krizaka/pacer…), never directly.",
+    },
+  },
+  create(context) {
+    /** @param {Node | null | undefined} source */
+    const check = (source) => {
+      if (source?.type === "Literal" && typeof source.value === "string" && source.value.startsWith(TANSTACK_SCOPE)) {
+        context.report({ node: source, messageId: "tanstack", data: { source: source.value } });
+      }
+    };
+    return {
+      ImportDeclaration: (node) => check(node.source),
+      ExportNamedDeclaration: (node) => check(node.source),
+      ExportAllDeclaration: (node) => check(node.source),
+      ImportExpression: (node) => check(node.source),
+      "CallExpression[callee.name='require']": (/** @type {import("estree").CallExpression} */ node) =>
+        check(/** @type {Node} */ (node.arguments[0])),
+    };
+  },
+};
+
 /** Oussama, 2026-10-22: « changer les tabs doit changer les routes » — a selection of a page lives in the URL. */
 /** @type {RuleModule} */
 export const routeStateSelection = {
@@ -169,7 +245,16 @@ export function ownProductPrefix(cwd) {
   for (let dir = cwd; ; dir = dirname(dir)) {
     const file = join(dir, "package.json");
     if (existsSync(file)) {
-      found = productPrefixOf(file);
+      try {
+        const name = String(JSON.parse(readFileSync(file, "utf8")).name ?? "");
+        // A product names its packages `<product>-<part>` (acme-monorepo, @org/acme-admin); a one-word package
+        // (@org/realtime, @org/ui) is a building block, not a product, and a context word is never one.
+        const words = name.replace(/^@[^/]+\//, "").split(/[-_.]/).filter(Boolean);
+        const word = words.length > 1 ? words[0].toUpperCase() : "";
+        found = /^[A-Z][A-Z0-9]+$/.test(word) && !ENV_CONTEXT_WORDS.includes(word) ? word : null;
+      } catch {
+        found = null;
+      }
       break;
     }
     if (dirname(dir) === dir) break;
@@ -178,24 +263,6 @@ export function ownProductPrefix(cwd) {
   return found;
 }
 
-/**
- * The product word of one package.json (see `ownProductPrefix`); null when it cannot be read or is not a product.
- * @param {string} file
- * @returns {string | null}
- */
-function productPrefixOf(file) {
-  try {
-    const name = String(JSON.parse(readFileSync(file, "utf8")).name ?? "");
-    // A product names its packages `<product>-<part>` (acme-monorepo, @org/acme-admin); a one-word package
-    // (@org/realtime, @org/ui) is a building block, not a product, and a context word is never one.
-    const words = name.replace(/^@[^/]+\//, "").split(/[-_.]/).filter(Boolean);
-    const word = words.length > 1 ? words[0].toUpperCase() : "";
-    return /^[A-Z][A-Z0-9]+$/.test(word) && !ENV_CONTEXT_WORDS.includes(word) ? word : null;
-  } catch {
-    return null;
-  }
-}
-
 /** Vendors: a vendor is a value (`MEDIA_STORAGE_PROVIDER=bunny`, `MAIL_PROVIDER=mailgun`), never a name. */
 export const ENV_VENDOR_PREFIXES = Object.freeze([
   "BUNNY", "MAILGUN", "RESEND", "SENDGRID", "POSTMARK", "STRIPE", "CCBILL", "SEGPAY", "NOWPAYMENTS", "PAYPAL",
@@ -325,3 +392,28 @@ export const noRawPalette = classNameRule(
   ({ allow = [] }) => new RegExp(paletteSource(allow)),
   "Raw palette colour: use a role (bg-surface-1, text-fg-secondary, border-border-default, text-accent, text-danger).",
 );
+
+/** Oussama, 2026-10-22: pages are composed from Krizaka UI's templates, never hand-built. */
+/** @type {RuleModule} */
+export const pageTemplate = {
+  meta: {
+    type: "problem",
+    docs: { description: "Every page of the app router declares the Krizaka UI template it composes: `// @template: app-settings`." },
+    schema: [],
+    messages: {
+      missing: "This page declares no template. Compose one of the page templates of @krizaka/ui (ui.krizaka.com/templates) and say so with `// @template: <name>` at the top of the file. A page that really fits none says why: `// @template: custom: <reason>`.",
+      unknown: "Unknown template « {{ name }} ». The templates are: {{ list }}, or `custom: <reason>`.",
+      reason: "`// @template: custom` needs its reason: `// @template: custom: a canvas editor, no template fits`.",
+    },
+  },
+  create(context) {
+    if (!isPageFile(context.filename)) return {};
+    return {
+      Program: (/** @type {Node} */ node) => {
+        const problem = pageTemplateProblem(context.sourceCode.text);
+        if (!problem) return;
+        context.report({ node, loc: { line: 1, column: 0 }, messageId: problem.kind, data: { name: "name" in problem ? problem.name : "", list: PAGE_TEMPLATES.join(", ") } });
+      },
+    };
+  },
+};

package/eslint/stack.js

@@ -1,20 +1,25 @@
-// The stack rules (the stack ADR, decisions S1–S3): server state through @krizaka/query, tables and forms through
-// @krizaka/ui. The import of TanStack (S11) is a dependency-cruiser rule now, `krizaka-first-query`: one tool, one rule.
-// Warnings: krizaka-ratchet counts the same patterns, so an app adopts them now and brings each count to 0 by the end
-// of its adoption.
+// The stack rules (the stack ADR, decisions S1–S3 and S11): server state through @krizaka/query, tables and forms
+// through @krizaka/ui, TanStack only behind a @krizaka facade. Warnings: krizaka-ratchet counts the same patterns, so an
+// app adopts them now and brings each count to 0 by the end of its adoption.
 import { krizakaPlugin } from "./plugin.js";
 
 /** The rule names, as configured. */
 export const STACK_RULES = Object.freeze([
   "krizaka/no-fetch-in-client-effect",
+  "krizaka/no-async-in-effect",
+  "krizaka/no-derived-state-in-effect",
+  "krizaka/no-direct-tanstack-import",
   "krizaka/no-local-table-or-form",
   "krizaka/no-family-switcher",
   "krizaka/route-state-selection",
+  "krizaka/page-template",
 ]);
 
 /**
- * Flat config: the stack rules on an app's sources.
- * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", maxFormFields?: number }} [options]
+ * Flat config: the three stack rules on an app's sources.
+ * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", effects?: "warn" | "error" | "off", maxFormFields?: number }} [options]
+ *   `effects`: severity of the two effect rules (react-effects standard): `"error"` by default; a repository with debt
+ *   passes `"warn"` while `krizaka-ratchet` (asyncInEffect, derivedStateInEffect) brings the count to 0.
  *   `maxFormFields`: a form with at most this many fields is allowed (default 1 — a search box, a newsletter).
  * @returns {import("eslint").Linter.Config[]}
  */
@@ -22,6 +27,7 @@ export function krizakaStack({
   files = ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
   ignores = [],
   severity = "warn",
+  effects = "error",
   maxFormFields = 1,
 } = {}) {
   return [
@@ -32,11 +38,17 @@ export function krizakaStack({
       plugins: { krizaka: krizakaPlugin },
       rules: {
         "krizaka/no-fetch-in-client-effect": severity,
+        // useEffect is for the outside world: data is useQuery/useMutation, derived state is computed in render.
+        "krizaka/no-async-in-effect": effects,
+        "krizaka/no-derived-state-in-effect": effects,
+        "krizaka/no-direct-tanstack-import": severity,
         "krizaka/no-local-table-or-form": [severity, { maxFormFields }],
         // Never a warning: the family switcher is gone from every site (krizaka.com is the only way back).
         "krizaka/no-family-switcher": "error",
         // A selection of a view (tabs, segmented, toggles, chip groups) lives in the URL, not in local state.
         "krizaka/route-state-selection": severity,
+        // Every page of the app router composes a Krizaka UI template and says which (// @template: app-settings).
+        "krizaka/page-template": severity,
       },
     },
   ];