@krizaka/config 0.7.0 → 0.8.1

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,9 @@ 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/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. |
@@ -81,17 +83,15 @@ 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 three stack rules
+### The 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.
 
@@ -104,8 +104,55 @@ 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`).
@@ -184,4 +231,4 @@ The CI step, after the install:
 
 ## License
 
-[Apache-2.0](../../LICENSE)
+[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/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, noDirectTanstackImport, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
+import { envName, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
 
 /** @type {import("eslint").ESLint.Plugin} */
 export const krizakaPlugin = {
@@ -8,7 +8,6 @@ export const krizakaPlugin = {
   rules: {
     "no-locale-ternary": noLocaleTernaryRule,
     "no-fetch-in-client-effect": noFetchInClientEffect,
-    "no-direct-tanstack-import": noDirectTanstackImport,
     "no-local-table-or-form": noLocalTableOrForm,
     "no-light-variant": noLightVariant,
     "no-raw-palette": noRawPalette,

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, TANSTACK_SCOPE } from "../patterns.js";
+import { countFormFields, EFFECT_NAMES_SOURCE, FETCH_NAMES_SOURCE, isLocalSelection, LIGHT_VARIANT_SOURCE, paletteSource } from "../patterns.js";
 
 /** @typedef {import("eslint").Rule.RuleModule} RuleModule */
 /** @typedef {import("estree").Node} Node */
@@ -70,36 +70,6 @@ export const noFetchInClientEffect = {
   },
 };
 
-/** 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 = {
@@ -199,16 +169,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;
@@ -217,6 +178,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",

package/eslint/stack.js

@@ -1,19 +1,19 @@
-// The three 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. */
 export const STACK_RULES = Object.freeze([
   "krizaka/no-fetch-in-client-effect",
-  "krizaka/no-direct-tanstack-import",
   "krizaka/no-local-table-or-form",
   "krizaka/no-family-switcher",
   "krizaka/route-state-selection",
 ]);
 
 /**
- * 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", maxFormFields?: number }} [options]
  *   `maxFormFields`: a form with at most this many fields is allowed (default 1 — a search box, a newsletter).
  * @returns {import("eslint").Linter.Config[]}
@@ -32,7 +32,6 @@ export function krizakaStack({
       plugins: { krizaka: krizakaPlugin },
       rules: {
         "krizaka/no-fetch-in-client-effect": severity,
-        "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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@krizaka/config",
-  "version": "0.7.0",
-  "description": "The shared configuration of every Krizaka JavaScript repository: ESLint flat configs (base, Next.js, the four UI rules, the three stack rules, no locale ternary), the dependency-cruiser boundary, tsconfig bases, Prettier, EditorConfig, and the krizaka-ratchet debt counter.",
+  "version": "0.8.1",
+  "description": "The shared configuration of every Krizaka JavaScript repository: ESLint flat configs (base, Next.js, the four UI rules, the stack rules, no locale ternary), the « Krizaka first » covered-domains map and the dependency-cruiser preset generated from it (refused imports, cycles, unresolvable imports, dev dependencies), tsconfig bases, Prettier, EditorConfig, and the krizaka-ratchet and krizaka-known-violations debt counters.",
   "keywords": [
     "krizaka",
     "eslint-config",
@@ -10,13 +10,14 @@
     "ratchet",
     "design-system",
     "dependency-cruiser",
-    "tanstack"
+    "tanstack",
+    "krizaka-first"
   ],
-  "homepage": "https://ui.krizaka.com/packages/config",
-  "bugs": "https://github.com/krizaka/krizaka-ui/issues",
+  "homepage": "https://ts.krizaka.com/config",
+  "bugs": "https://github.com/krizaka/krizaka-ts/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/krizaka/krizaka-ui.git",
+    "url": "git+https://github.com/krizaka/krizaka-ts.git",
     "directory": "packages/config"
   },
   "license": "Apache-2.0",
@@ -32,6 +33,9 @@
     "./eslint/env-names": "./eslint/env-names.js",
     "./eslint/plugin": "./eslint/plugin.js",
     "./dependency-cruiser": "./dependency-cruiser.cjs",
+    "./covered-domains": "./covered-domains.cjs",
+    "./covered-domains.json": "./covered-domains.json",
+    "./known-violations": "./ratchet/known-violations.js",
     "./patterns": "./patterns.js",
     "./ratchet": "./ratchet/ratchet.js",
     "./prettier": "./prettier.config.js",
@@ -43,7 +47,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "krizaka-ratchet": "./bin/krizaka-ratchet.mjs"
+    "krizaka-ratchet": "./bin/krizaka-ratchet.mjs",
+    "krizaka-known-violations": "./bin/krizaka-known-violations.mjs"
   },
   "files": [
     "bin",
@@ -52,6 +57,8 @@
     "tsconfig",
     "patterns.js",
     "dependency-cruiser.cjs",
+    "covered-domains.cjs",
+    "covered-domains.json",
     "prettier.config.js",
     ".editorconfig",
     "README.md",
@@ -60,6 +67,7 @@
   "sideEffects": false,
   "dependencies": {
     "@eslint/js": "^9.39.0 || ^10.0.0",
+    "dependency-cruiser": "^18.6.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "globals": "^17.13.0",
@@ -84,10 +92,9 @@
     "@size-limit/file": "^14.2.0",
     "@types/estree": "^1.0.8",
     "@types/node": "^22.15.0",
-    "dependency-cruiser": "^18.6.0",
     "eslint": "^9.39.0",
     "eslint-config-next": "^16.4.0",
-    "next": "^16.4.0",
+    "next": "^16.4.1",
     "prettier": "^3.9.9",
     "publint": "^0.3.25",
     "size-limit": "^14.2.0",
@@ -117,6 +124,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "size": "size-limit",
-    "publint": "publint"
+    "publint": "publint",
+    "check": "pnpm run lint && pnpm run test && pnpm run size && pnpm run publint"
   }
 }

package/patterns.js

@@ -102,20 +102,40 @@ export function balancedArguments(source, open) {
   let depth = 0;
   for (let i = open; i < source.length; i += 1) {
     const c = source[i];
-    if (c === '"' || c === "'" || c === "`") {
-      for (i += 1; i < source.length && source[i] !== c; i += 1) if (source[i] === "\\") i += 1;
-    } else if (c === "/" && source[i + 1] === "/") {
-      i = source.indexOf("\n", i);
-      if (i < 0) break;
-    } else if (c === "/" && source[i + 1] === "*") {
-      i = source.indexOf("*/", i + 2) + 1;
-      if (i <= 0) break;
-    } else if (c === "(") depth += 1;
+    const skipped = skipLiteralOrComment(source, i);
+    if (skipped === null) break;
+    if (skipped > i) i = skipped;
+    else if (c === "(") depth += 1;
     else if (c === ")" && --depth === 0) return source.slice(open + 1, i);
   }
   return source.slice(open + 1);
 }
 
+/**
+ * Where a string, template or comment that starts at `i` ends (the index of its last character), `i` itself when none starts
+ * there, null when a line comment or a block comment never ends.
+ * @param {string} source
+ * @param {number} i
+ * @returns {number | null}
+ */
+function skipLiteralOrComment(source, i) {
+  const c = source[i];
+  if (c === '"' || c === "'" || c === "`") {
+    let end = i + 1;
+    while (end < source.length && source[end] !== c) end += source[end] === "\\" ? 2 : 1;
+    return end;
+  }
+  if (c === "/" && source[i + 1] === "/") {
+    const end = source.indexOf("\n", i);
+    return end < 0 ? null : end;
+  }
+  if (c === "/" && source[i + 1] === "*") {
+    const end = source.indexOf("*/", i + 2);
+    return end < 0 ? null : end + 1;
+  }
+  return i;
+}
+
 // ── Selections live in the URL (Oussama, 2026-10-22: « changer les tabs doit changer les routes ») ──────────────────────
 // Read by the ESLint rule krizaka/route-state-selection and by the ratchet.
 

package/ratchet/known-violations.js

@@ -0,0 +1,116 @@
+// The known violations of dependency-cruiser, held so that they only shrink (krizaka-ui#612). An app that adopts the
+// import rules late records what it already breaks in `.dependency-cruiser-known-violations.json` (the format of
+// `depcruise-baseline`, read by `depcruise --ignore-known`); this module compares that file with a real run:
+//   - a violation that is not recorded is new: refused (`depcruise --ignore-known` refuses it as well);
+//   - a recorded violation that is gone is a gain: `update` removes it, `check` refuses to leave it recorded, so the
+//     file cannot hide a regression later;
+//   - `update` never adds a line. `init` writes the file once, when it does not exist (the adoption pull request).
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const KNOWN_FILE = ".dependency-cruiser-known-violations.json";
+export const CONFIG_FILE = ".dependency-cruiser.cjs";
+
+/** @typedef {{ type?: string, from: string, to: string, rule: { name: string, severity?: string }, cycle?: { name: string }[] }} Violation */
+
+/** The identity of a violation, as depcruise matches it: the rule, the two ends, and the cycle's modules. @param {Violation} v */
+export const keyOf = (v) => [v.rule.name, v.from, v.to, ...(v.cycle ?? []).map((step) => step.name)].join("\u0000");
+
+/**
+ * Compare the recorded violations with the current ones.
+ * @param {Violation[]} known
+ * @param {Violation[]} current
+ */
+export function compare(known, current) {
+  const knownKeys = new Set(known.map(keyOf));
+  const currentKeys = new Set(current.map(keyOf));
+  return {
+    added: current.filter((v) => !knownKeys.has(keyOf(v))),
+    gone: known.filter((v) => !currentKeys.has(keyOf(v))),
+  };
+}
+
+/** What `update` writes: the recorded violations that still happen. Never a new one. @param {Violation[]} known @param {Violation[]} current */
+export const shrink = (known, current) => known.filter((v) => current.some((c) => keyOf(c) === keyOf(v)));
+
+/** @param {Violation} v */
+const describe = (v) => `${v.rule.name}: ${v.from} -> ${v.to}${v.cycle ? ` (cycle: ${v.cycle.map((step) => step.name).join(" -> ")})` : ""}`;
+
+/**
+ * The app's own dependency-cruiser first (its version is the one `depcruise` runs), then the one this package depends on.
+ * dependency-cruiser is ESM-only and hides its bin from `exports`: walk up `node_modules` from the app, then resolve the entry.
+ * @param {string} cwd
+ */
+function resolveDepcruise(cwd) {
+  const bin = (/** @type {string} */ root) => join(root, "bin", "dependency-cruiser.mjs");
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    const candidate = bin(join(dir, "node_modules", "dependency-cruiser"));
+    if (existsSync(candidate)) return candidate;
+    if (dirname(dir) === dir) break;
+  }
+  let root = dirname(fileURLToPath(import.meta.resolve("dependency-cruiser")));
+  while (!existsSync(bin(root)) && dirname(root) !== root) root = dirname(root);
+  if (existsSync(bin(root))) return bin(root);
+  throw new Error("dependency-cruiser is not installed here: add it to the devDependencies.");
+}
+
+/**
+ * Run dependency-cruiser without the known file and read every violation (the `baseline` report).
+ * @param {{ cwd: string, config: string, targets: string[] }} options
+ * @returns {Violation[]}
+ */
+export function currentViolations({ cwd, config, targets }) {
+  const bin = resolveDepcruise(cwd);
+  const run = spawnSync(process.execPath, [bin, ...targets, "--config", config, "--output-type", "baseline"], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+  });
+  try {
+    return JSON.parse(run.stdout);
+  } catch {
+    throw new Error(`dependency-cruiser failed:\n${run.stderr || run.stdout}`);
+  }
+}
+
+/** @param {string} file @returns {Violation[]} */
+const readKnown = (file) => JSON.parse(readFileSync(file, "utf8"));
+/** @param {string} file @param {Violation[]} violations */
+const writeKnown = (file, violations) => writeFileSync(file, `${JSON.stringify(violations, null, 2)}\n`);
+
+/**
+ * `check` | `update` | `init`. Returns the exit code and the lines to print.
+ * @param {"check" | "update" | "init"} command
+ * @param {{ cwd?: string, config?: string, known?: string, targets: string[] }} options
+ * @returns {{ code: number, lines: string[] }}
+ */
+export function runKnownViolations(command, { cwd = process.cwd(), config = CONFIG_FILE, known = KNOWN_FILE, targets }) {
+  const file = resolve(cwd, known);
+  const current = currentViolations({ cwd, config, targets });
+  if (command === "init") {
+    if (existsSync(file)) return { code: 1, lines: [`${known} exists: the baseline is written once. Use "update" to lower it.`] };
+    writeKnown(file, current);
+    return { code: 0, lines: [`${known}: ${current.length} known violations recorded. They only go down.`] };
+  }
+  const recorded = existsSync(file) ? readKnown(file) : [];
+  const { added, gone } = compare(recorded, current);
+  if (command === "update") {
+    writeKnown(file, shrink(recorded, current));
+    const lines = [`${known}: ${recorded.length} -> ${recorded.length - gone.length} known violations.`];
+    if (added.length > 0) {
+      lines.push(`${added.length} new violation(s) are NOT recorded (the baseline never grows). Fix them:`, ...added.map((v) => `  ${describe(v)}`));
+      return { code: 1, lines };
+    }
+    return { code: 0, lines };
+  }
+  const lines = [
+    ...added.map((v) => `new: ${describe(v)}`),
+    ...gone.map((v) => `fixed but still recorded: ${describe(v)}`),
+  ];
+  if (added.length > 0) lines.push("A new violation is never recorded: fix it (missing function? add it to the Krizaka package first).");
+  if (gone.length > 0) lines.push(`Lock the gain: krizaka-known-violations update (${gone.length} fewer).`);
+  if (lines.length === 0) lines.push(`${known}: ${recorded.length} known violations, none new, none fixed.`);
+  return { code: added.length + gone.length > 0 ? 1 : 0, lines };
+}

package/ratchet/ratchet.js

@@ -2,7 +2,7 @@
 // Same patterns as the ESLint rules (../patterns.js), applied to the source text: the counter sees every
 // occurrence (a class in a `cn()` argument or a constant too), so it can only be stricter than the rule.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 
 import { glob } from "tinyglobby";
 
@@ -190,6 +190,25 @@ export class RatchetError extends Error {}
  * @property {boolean} written the ratchet file was created, lowered or completed
  */
 
+/**
+ * Each counter against its recorded value: the report, and the names that went up or down.
+ * @param {Counters} current
+ * @param {Counters} recorded
+ */
+function compareCounters(current, recorded) {
+  /** @type {RatchetResult["counters"]} */
+  const report = /** @type {any} */ ({});
+  /** @type {CounterName[]} */ const increased = [];
+  /** @type {CounterName[]} */ const decreased = [];
+  for (const name of COUNTERS) {
+    const delta = current[name] - recorded[name];
+    report[name] = { recorded: recorded[name], current: current[name], delta };
+    if (delta > 0) increased.push(name);
+    if (delta < 0) decreased.push(name);
+  }
+  return { report, increased, decreased };
+}
+
 /**
  * Runs the ratchet.
  * - `check` (default): fails when a counter is above its recorded value.
@@ -201,6 +220,11 @@ export class RatchetError extends Error {}
  */
 export async function runRatchet({ root, mode = "check", globs, file = RATCHET_FILE }) {
   const path = resolve(root, file);
+  // the ratchet file is read and written: it stays a .json file inside the repository root (no `../`, no absolute path elsewhere)
+  const inside = relative(resolve(root), path);
+  if (!path.endsWith(".json") || inside === "" || inside.startsWith("..") || isAbsolute(inside)) {
+    throw new RatchetError(`${file}: the ratchet file must be a .json file inside ${root}.`);
+  }
   const exists = existsSync(path);
   if (mode === "init" && exists) throw new RatchetError(`${file} already exists: use --update to lower it.`);
   if (mode !== "init" && !exists) throw new RatchetError(`${file} not found in ${root}: run krizaka-ratchet --init first.`);
@@ -222,16 +246,7 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
   /** @type {CounterName[]} */ const added = recordedFile ? COUNTERS.filter((n) => recordedFile.counters[n] === undefined) : [];
   const recorded = /** @type {Counters} */ ({ ...current, ...recordedFile?.counters });
 
-  /** @type {RatchetResult["counters"]} */
-  const report = /** @type {any} */ ({});
-  /** @type {CounterName[]} */ const increased = [];
-  /** @type {CounterName[]} */ const decreased = [];
-  for (const name of COUNTERS) {
-    const delta = current[name] - recorded[name];
-    report[name] = { recorded: recorded[name], current: current[name], delta };
-    if (delta > 0) increased.push(name);
-    if (delta < 0) decreased.push(name);
-  }
+  const { report, increased, decreased } = compareCounters(current, recorded);
 
   let written = false;
   if (mode === "init") {