@krizaka/config 0.9.0 → 0.10.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)](../../LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/krizaka/krizaka-ts/blob/main/LICENSE)
 
 ## Adopt it in three lines
 
@@ -24,7 +24,7 @@ export default [...krizakaNext, ...krizakaUi(), ...krizakaStack(), ...noLocaleTe
 ```
 
 ```js
-// .dependency-cruiser.cjs — the TanStack boundary, plus the app's own rules
+// .dependency-cruiser.cjs — « Krizaka first », cycles, unresolvable imports, dev dependencies, plus the app's own rules
 module.exports = { extends: "@krizaka/config/dependency-cruiser", forbidden: [] };
 ```
 
@@ -51,7 +51,10 @@ 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: `krizaka-no-direct-tanstack` (no `@tanstack/*` from an app). |
+| `@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-server-client-boundary` (bin) · `@krizaka/config/server-client-boundary` | Fails when a server-rendered module imports a function from a `"use client"` `@krizaka/*` module (React #441), see below. |
 | `@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. |
@@ -96,15 +99,13 @@ read any file (a Vite/Tauri app has no `"use client"`).
 
 ### The three stack rules
 
-From [ADR-001](../../docs/adr/ADR-001-tanstack-under-krizaka-facades.md) — the TanStack engines run headless, behind
+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
 `@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-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
+2. **`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.
 
@@ -117,12 +118,74 @@ krizakaStack({
 });
 ```
 
-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/*`.
+### « 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.
 
 `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`).
 
+### Server/client boundary (`krizaka-server-client-boundary`)
+
+A Next.js server module that calls a function exported by a `"use client"` module (`readFilterParams()` of
+`@krizaka/ui/filter-bar`) crashes the page with React error #441. Unit tests ignore the directive and `next build` does not
+see it. Every Next.js App Router app runs the guard in its lint:
+
+```sh
+krizaka-server-client-boundary                 # from the app's folder: reads app/ or src/app/ and the "@/*" alias of tsconfig.json
+krizaka-server-client-boundary --root apps/web --app app --scope @krizaka
+```
+
+It walks the pages, layouts and routes, then every local module they import, and stops at a `"use client"` file. A lowercase
+value import (a function, a hook, a constant) from a client module of the scope is an offence; components and `import type`
+are fine. Render a component, or move the function to a plain module. `checkBoundary()` is also exported for a test.
+
 ### Environment variable names (`krizaka/env-name`)
 
 Environment variables are named by bounded context (krizaka/.github#46): `<CONTEXT>_<THING>` with CONTEXT one of
@@ -199,9 +262,4 @@ The CI step, after the install:
 
 ## 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.
+[Apache-2.0](https://github.com/krizaka/krizaka-ts/blob/main/LICENSE)

package/bin/krizaka-known-violations.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// krizaka-known-violations: the known violations of dependency-cruiser, which only shrink.
+import { CONFIG_FILE, KNOWN_FILE, runKnownViolations } from "../ratchet/known-violations.js";
+
+const USAGE = `Usage: krizaka-known-violations <check|update|init> [--config ${CONFIG_FILE}] [--known ${KNOWN_FILE}] <folder…>
+
+  check    fails on a violation that is not recorded, and on a recorded one that is fixed (lock the gain with update)
+  update   removes the fixed violations from the file; never adds one
+  init     writes the file once, for an app that adopts the rules (the adoption pull request)
+
+Run it from the app's folder. Beside it, \`depcruise --ignore-known\` ignores the recorded ones.`;
+
+const args = process.argv.slice(2);
+const command = args.shift();
+/** @type {{ config?: string, known?: string, targets: string[] }} */
+const options = { targets: [] };
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i] ?? "";
+  if (arg === "--config") options.config = args[++i];
+  else if (arg === "--known") options.known = args[++i];
+  else options.targets.push(arg);
+}
+
+if ((command !== "check" && command !== "update" && command !== "init") || options.targets.length === 0) {
+  console.error(USAGE);
+  process.exit(2);
+}
+try {
+  const { code, lines } = runKnownViolations(command, options);
+  for (const line of lines) (code === 0 ? console.log : console.error)(line);
+  process.exit(code);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/bin/krizaka-ratchet.mjs

@@ -30,7 +30,6 @@ const LABELS = {
   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/bin/krizaka-server-client-boundary.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// krizaka-server-client-boundary: no server-rendered module calls a function exported by a "use client" Krizaka module (React #441).
+import { checkBoundary, DEFAULT_SCOPE } from "../ratchet/server-client-boundary.js";
+
+const USAGE = `Usage: krizaka-server-client-boundary [--root <app folder>] [--app <app router folder>] [--alias <folder of "@/">] [--scope ${DEFAULT_SCOPE}]
+
+Walks what the server renders (pages, layouts, routes and the local modules they import, down to a "use client" file) and fails
+when one imports a function (a lowercase export) from a "use client" module of the scope: the server would call a client
+reference and the page would crash (React error #441). Render a component, or move the function to a plain module.`;
+
+const options = {};
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "--root") options.root = args[++i];
+  else if (arg === "--app") options.appDir = args[++i];
+  else if (arg === "--alias") options.alias = args[++i];
+  else if (arg === "--scope") options.scope = args[++i];
+  else {
+    console.error(USAGE);
+    process.exit(2);
+  }
+}
+try {
+  const { seen, offences } = checkBoundary(options);
+  if (offences.length === 0) {
+    console.log(`krizaka-server-client-boundary: ${seen.size} server modules checked, no client function called from the server.`);
+  } else {
+    console.error(`krizaka-server-client-boundary: ${offences.length} server module(s) import a function from a "use client" module (React #441):`);
+    for (const line of offences) console.error(`  ${line}`);
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/covered-domains.cjs

@@ -0,0 +1,50 @@
+// The covered-domains map (covered-domains.json) and what is generated from it: dependency-cruiser patterns, the message
+// that names the Krizaka home, the table of the « Use Krizaka first » page. CommonJS: dependency-cruiser `require`s its
+// configs, and Node imports it from ESM (`import { coveredDomains } from "@krizaka/config/covered-domains"`).
+
+const map = require("./covered-domains.json");
+
+/** @typedef {{ id: string, title: string, home: string, use: string, refused: string[] }} CoveredDomain */
+
+/** The domains, in the order of the map. @type {readonly CoveredDomain[]} */
+const coveredDomains = Object.freeze(map.domains);
+
+/** The last thing every message says. */
+const MISSING_FUNCTION = "Missing function? add it to the package first.";
+
+/** @param {string} text */
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The dependency-cruiser `to.path` regular expression of a refused entry. It matches the resolved file
+ * (`…/node_modules/dayjs/index.js`, also under pnpm's `.pnpm/…/node_modules/`) and the module as written when it could not
+ * be resolved (`dayjs`), never a local folder called `dayjs`.
+ * `@scope/*` is a scope, `prefix*` a name prefix, anything else a package and its subpaths.
+ * @param {string} entry
+ */
+function refusedPattern(entry) {
+  const start = "(^|(^|/)node_modules/)";
+  if (entry.endsWith("/*")) return `${start}${escapeRegExp(entry.slice(0, -1))}`;
+  if (entry.endsWith("*")) return `${start}${escapeRegExp(entry.slice(0, -1))}[^/]*(/|$)`;
+  return `${start}${escapeRegExp(entry)}(/|$)`;
+}
+
+/** One pattern for a whole domain. @param {CoveredDomain} domain */
+const domainPattern = (domain) => domain.refused.map(refusedPattern).join("|");
+
+/** The message of a domain: what is refused, the Krizaka home, and what to do when the function is missing. @param {CoveredDomain} domain */
+const domainMessage = (domain) =>
+  `Krizaka first (${domain.id}): this library is refused in an app. Use ${domain.use}. ${MISSING_FUNCTION}`;
+
+/** The name of the dependency-cruiser rule of a domain. @param {CoveredDomain | string} domain */
+const ruleName = (domain) => `krizaka-first-${typeof domain === "string" ? domain : domain.id}`;
+
+/** The table of the page « Use Krizaka first » (Markdown), generated from the map. */
+function coveredDomainsMarkdown() {
+  const rows = coveredDomains.map(
+    (domain) => `| ${domain.title} | ${domain.use} | ${domain.refused.map((entry) => `\`${entry}\``).join(", ")} | \`${ruleName(domain)}\` |`,
+  );
+  return ["| Domain | Use | Refused in an app | Rule |", "| :-- | :-- | :-- | :-- |", ...rows].join("\n");
+}
+
+module.exports = { coveredDomains, domainMessage, domainPattern, coveredDomainsMarkdown, MISSING_FUNCTION, refusedPattern, ruleName };

package/covered-domains.json

@@ -0,0 +1,40 @@
+{
+  "$comment": "The covered-domains map of « Krizaka first » (krizaka-ui#609, #612; krizaka/.github docs/quality-controls.md §5.1). THE single source: the dependency-cruiser preset generates one `krizaka-first-<id>` rule per domain from it, and the page « Use Krizaka first » of ui.krizaka.com is laid out from it. `refused`: a package name (`dayjs`, also its subpaths), a prefix (`date-fns*`) or a scope (`@tanstack/*`). A Krizaka package (`@krizaka/*`, in node_modules) is the facade and is never checked. Add a domain here, never in a tool's config.",
+  "domains": [
+    {
+      "id": "dates",
+      "title": "Dates, times and local days",
+      "home": "@krizaka/intl",
+      "use": "`@krizaka/intl` (formatting, the local day with `localDay`) or `@krizaka/time` (date arithmetic, a facade created on the first real need: krizaka-ts#76)",
+      "refused": ["date-fns*", "@date-fns/*", "dayjs", "luxon", "moment", "moment-timezone"]
+    },
+    {
+      "id": "i18n",
+      "title": "Words, languages and messages",
+      "home": "@krizaka/i18n",
+      "use": "`@krizaka/i18n`",
+      "refused": ["i18next*", "react-i18next", "next-intl", "next-i18next", "react-intl", "@formatjs/*", "@lingui/*", "i18n-js", "typesafe-i18n"]
+    },
+    {
+      "id": "query",
+      "title": "Data fetching, cache, tables, forms and virtual lists",
+      "home": "@krizaka/query",
+      "use": "`@krizaka/query` for server state, and `@krizaka/ui` (`data-table`, `form`, `virtual`) or `@krizaka/pacer` for the other TanStack engines",
+      "refused": ["@tanstack/*"]
+    },
+    {
+      "id": "icons",
+      "title": "Icons",
+      "home": "@krizaka/icons",
+      "use": "`@krizaka/icons`",
+      "refused": ["lucide-react", "react-icons", "@heroicons/*"]
+    },
+    {
+      "id": "ui",
+      "title": "Interface primitives",
+      "home": "@krizaka/ui",
+      "use": "`@krizaka/ui`",
+      "refused": ["@radix-ui/*", "radix-ui"]
+    }
+  ]
+}

package/dependency-cruiser.cjs

@@ -1,31 +1,79 @@
-// The shared dependency-cruiser rules of a Krizaka app (the stack ADR, decision S11). An app extends it and adds its own:
+// 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:
 //
 //   // .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).
 
-/** @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/" },
-    },
-  ],
-  options: {
-    doNotFollow: { path: "(^|/)node_modules/" },
-    tsPreCompilationDeps: true,
-    enhancedResolveOptions: {
-      exportsFields: ["exports"],
-      conditionNames: ["import", "require", "node", "default"],
+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"],
+      },
     },
-  },
-};
+  };
+}
+
+module.exports = createConfig();
+// not enumerable: dependency-cruiser validates the keys of the configuration it loads
+Object.defineProperty(module.exports, "withOptions", { value: createConfig, enumerable: false });

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, noAsyncInEffect, noDerivedStateInEffect, noDirectTanstackImport, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,pageTemplate, routeStateSelection } from "./rules.js";
+import { envName, noAsyncInEffect, noDerivedStateInEffect, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
 
 /** @type {import("eslint").ESLint.Plugin} */
 export const krizakaPlugin = {
@@ -10,14 +10,12 @@ export const krizakaPlugin = {
     "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, effectProblem, FETCH_NAMES_SOURCE, isLocalSelection, isPageFile, LIGHT_VARIANT_SOURCE, PAGE_TEMPLATES, pageTemplateProblem, paletteSource, TANSTACK_SCOPE } from "../patterns.js";
+import { countFormFields, EFFECT_NAMES_SOURCE, effectProblem, FETCH_NAMES_SOURCE, isLocalSelection, LIGHT_VARIANT_SOURCE, paletteSource } from "../patterns.js";
 
 /** @typedef {import("eslint").Rule.RuleModule} RuleModule */
 /** @typedef {import("estree").Node} Node */
@@ -116,36 +116,6 @@ export const noDerivedStateInEffect = {
   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 = {
@@ -245,16 +215,7 @@ export function ownProductPrefix(cwd) {
   for (let dir = cwd; ; dir = dirname(dir)) {
     const file = join(dir, "package.json");
     if (existsSync(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;
-      }
+      found = productPrefixOf(file);
       break;
     }
     if (dirname(dir) === dir) break;
@@ -263,6 +224,24 @@ 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",
@@ -392,28 +371,3 @@ 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,6 +1,7 @@
-// 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.
+// 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.
 import { krizakaPlugin } from "./plugin.js";
 
 /** The rule names, as configured. */
@@ -8,15 +9,13 @@ 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 three stack rules on an app's sources.
+ * Flat config: the 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.
@@ -41,14 +40,11 @@ export function krizakaStack({
         // 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,
       },
     },
   ];