@krizaka/config 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # @krizaka/config
 
 **The shared configuration of every Krizaka JavaScript repository.** ESLint flat configs (base, Next.js, the four UI
-rules, no locale ternary), tsconfig bases, Prettier, EditorConfig — and `krizaka-ratchet`, the counter that keeps the
-UI debt from coming back.
+rules, the three stack rules, no locale ternary), the dependency-cruiser boundary, tsconfig bases, Prettier,
+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)
@@ -18,8 +18,14 @@ npm install -D @krizaka/config eslint typescript     # + eslint-config-next for
 import { krizakaNext } from "@krizaka/config/eslint/next";
 import { krizakaUi } from "@krizaka/config/eslint/krizaka-ui";
 import { noLocaleTernary } from "@krizaka/config/eslint/no-locale-ternary";
+import { krizakaStack } from "@krizaka/config/eslint/stack";
 
-export default [...krizakaNext, ...krizakaUi(), ...noLocaleTernary()];
+export default [...krizakaNext, ...krizakaUi(), ...krizakaStack(), ...noLocaleTernary()];
+```
+
+```js
+// .dependency-cruiser.cjs — the TanStack boundary, plus the app's own rules
+module.exports = { extends: "@krizaka/config/dependency-cruiser", forbidden: [] };
 ```
 
 ```jsonc
@@ -42,6 +48,9 @@ the package.
 | `@krizaka/config/eslint/next` | `krizakaNext`: `eslint-config-next` (core web vitals + TypeScript, which already carry typescript-eslint, React hooks and import) + the same basics. |
 | `@krizaka/config/eslint/krizaka-ui` | `krizakaUi(options?)`: the four UI rules below. Also `krizakaUiRules` and `krizakaUiRestrictedSyntax(options?)`. |
 | `@krizaka/config/eslint/no-locale-ternary` | `noLocaleTernary(options?)`: `krizaka/no-locale-ternary` — no `locale === "fr" ? … : …` outside routing code. |
+| `@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/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. |
@@ -71,19 +80,63 @@ 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
+
+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-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.
+
+```js
+krizakaStack({
+  files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"], // default
+  ignores: ["packages/**"],                        // e.g. the facades of a monorepo
+  severity: "warn",                                // default; "error" once the app's counts are at 0
+  maxFormFields: 1,                                // default
+});
+```
+
+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`).
 
+### Environment variable names (`krizaka/env-name`)
+
+Environment variables are named by bounded context (krizaka/.github#46): `<CONTEXT>_<THING>` with CONTEXT one of
+`APP_` `DATABASE_` `AUTH_` `MEDIA_` `MAIL_` `PUSH_` `PAYMENTS_` `REALTIME_` `ABUSE_` `OBSERVABILITY_` `AI_` `OPERATOR_`.
+The rule — on in `krizakaBase` and `krizakaNext` — refuses a name read through `process.env.X`, `process.env["X"]` or
+`import.meta.env.X` that starts (after `NEXT_PUBLIC_`, `EXPO_PUBLIC_` or `VITE_`) with:
+
+- a **product**: the organisation's name, the repository's own (the first word of its package.json name,
+  `acme-monorepo` → `ACME_`), or one you name — a deployment already says which product it is;
+- a **vendor** (`BUNNY_`, `MAILGUN_`, `RESEND_`, `STRIPE_`, `GOOGLE_`, `EXPO_`, `REDIS_`, `VERCEL_`…): the vendor is a
+  value (`MEDIA_STORAGE_PROVIDER=bunny`, `MAIL_PROVIDER=mailgun`) and its settings sit under the context
+  (`MEDIA_STORAGE_API_KEY`, `MAIL_API_KEY`).
+
+The platforms' own names (`GITHUB_TOKEN`, `VERCEL_URL`, `EAS_BUILD`, …) pass. Tune it with
+`envNames({ products, vendors, allow })` from `@krizaka/config/eslint/env-names`; `envNamePrefixProblem(name)` gives
+the same verdict to a script (a `.env.example` or deployment spec check).
+
 ## The ratchet
 
-A repository with debt cannot turn the UI rules on in one pull request. The ratchet lets it adopt them now: it counts
-the four debts, records the counts in `lint-ratchet.json` at the root, and **fails when a count goes up**. Every
-migration pull request lowers them; when a count reaches zero, the matching rule becomes a strict `error`.
+A repository with debt cannot turn the rules on in one pull request. The ratchet lets it adopt them now: it counts
+the four UI debts and the four stack debts, records the counts in `lint-ratchet.json` at the root, and **fails when a
+count goes up**. Every migration pull request lowers them; when a count reaches zero, the matching rule becomes a
+strict `error`.
 
 ```bash
 npx krizaka-ratchet --init      # once: creates lint-ratchet.json with today's counts — commit it
 npx krizaka-ratchet             # locally: compares (exit 1 when a count went up)
-npx krizaka-ratchet --update    # after a migration: lowers the recorded counts (never raises them) — commit it
+npx krizaka-ratchet --update    # after a migration: lowers the recorded counts (never raises them), records new counters — commit it
 npx krizaka-ratchet --json      # in CI: the same check, machine-readable
 ```
 
@@ -93,9 +146,16 @@ npx krizaka-ratchet --json      # in CI: the same check, machine-readable
 | `light` | `\blight:` |
 | `arbitraryVar` | `\[var\(--` |
 | `classNameTemplate` | `` className=\{\s*` `` |
-
-It scans `app/**/*.tsx`, `components/**/*.tsx` and `src/**/*.tsx` by default (`node_modules`, `dist`, `.next` never),
-or the globs given on the command line; `--init` stores them in the file so that every later run counts the same set.
+| `fetchInClientEffect` | in a file opening with `"use client"`: `fetch(` / `krizakaFetch(` between the parentheses of a `useEffect(` / `useLayoutEffect(` |
+| `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 |
+
+The UI counters scan `app/**/*.tsx`, `components/**/*.tsx` and `src/**/*.tsx` by default (`node_modules`, `dist`,
+`.next` never), or the globs given on the command line; the stack counters scan every source file (`js`, `jsx`, `mjs`,
+`ts`, `tsx`, `mts`) of `app`, `components`, `src`, `lib`, `hooks` and `features` (`stackGlobs`). `--init` stores both
+in the file so that every later run counts the same set. A file written before the stack counters still checks; the
+next `--update` records them at their current value.
 The counts apply the regex to the whole source text — a class held in a constant or a `cn()` argument counts too —
 so the ratchet is never looser than the rule. Exit codes: `0` ok, `1` a count went up, `2` usage or file error.
 
@@ -103,8 +163,14 @@ so the ratchet is never looser than the rule. Exit codes: `0` ok, `1` a count we
 // lint-ratchet.json
 {
   "globs": ["app/**/*.tsx", "components/**/*.tsx", "src/**/*.tsx"],
+  "stackGlobs": ["app/**/*.{js,jsx,mjs,ts,tsx,mts}", "…"],
   "allow": [],                                   // optional: same families as krizakaUi({ allow })
-  "counters": { "palette": 2400, "light": 1151, "arbitraryVar": 0, "classNameTemplate": 128 }
+  "retire": ["framer-motion"],                   // optional: dependencies on their way out
+  "maxFormFields": 1,                            // optional: same option as krizakaStack({ maxFormFields })
+  "counters": {
+    "palette": 2400, "light": 1151, "arbitraryVar": 0, "classNameTemplate": 128,
+    "fetchInClientEffect": 41, "directTanstackImport": 3, "localTableOrForm": 38, "retiredImport": 4
+  }
 }
 ```
 

package/bin/krizaka-ratchet.mjs

@@ -6,12 +6,14 @@ import { COUNTERS, RatchetError, runRatchet } from "../ratchet/ratchet.js";
 
 const USAGE = `Usage: krizaka-ratchet [globs…] [--init | --update] [--json] [--root <dir>] [--file <name>]
 
-Counts raw palette colours, light: variants, [var(--…)] utilities and className template strings in the
-source files (default: app/**/*.tsx components/**/*.tsx src/**/*.tsx) and compares them with lint-ratchet.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
+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
   --init     create lint-ratchet.json with the current counters
-  --update   lower the recorded counters to the current values (never raises them)
+  --update   lower the recorded counters to the current values (never raises them), record the new ones
   --json     machine-readable report on stdout (for CI)
   --root     repository root (default: current directory)
   --file     ratchet file name (default: lint-ratchet.json)`;
@@ -21,6 +23,10 @@ const LABELS = {
   light: "light: variants",
   arbitraryVar: "[var(--…)] utilities",
   classNameTemplate: "className template strings",
+  fetchInClientEffect: "fetch in a client effect",
+  directTanstackImport: "direct @tanstack/* imports",
+  localTableOrForm: "hand-written tables / forms",
+  retiredImport: "imports of retired deps",
 };
 
 let args;
@@ -61,7 +67,7 @@ try {
   if (values.json) {
     console.log(JSON.stringify(result, null, 2));
   } else {
-    console.log(`krizaka-ratchet — ${result.files} files (${result.globs.join(", ")})`);
+    console.log(`krizaka-ratchet — ${result.files} files for the UI, ${result.stackFiles} for the stack`);
     for (const name of COUNTERS) {
       const { recorded, current, delta } = result.counters[name];
       const mark = delta > 0 ? "✗" : delta < 0 ? "↓" : "=";
@@ -69,9 +75,14 @@ try {
       console.log(`  ${mark} ${LABELS[name].padEnd(28)} ${String(current).padStart(6)}  (recorded ${recorded}, ${sign})`);
     }
     if (result.mode === "init") console.log(`Created ${result.file}.`);
-    else if (result.written) console.log(`Lowered ${result.file}: commit it.`);
+    else if (result.written) console.log(`${result.decreased.length > 0 ? "Lowered" : "Completed"} ${result.file}: commit it.`);
     else if (result.decreased.length > 0) console.log(`Debt went down: run krizaka-ratchet --update and commit ${result.file}.`);
-    if (!result.ok) console.error(`Debt went up (${result.increased.join(", ")}): use the roles of @krizaka/tailwind and cn().`);
+    else if (result.added.length > 0) console.log(`New counters (${result.added.join(", ")}): run krizaka-ratchet --update and commit ${result.file}.`);
+    if (!result.ok) {
+      console.error(
+        `Debt went up (${result.increased.join(", ")}): roles of @krizaka/tailwind and cn() for the UI; @krizaka/query, @krizaka/ui/data-table and @krizaka/ui/form for the stack.`,
+      );
+    }
   }
   process.exit(result.ok ? 0 : 1);
 } catch (error) {

package/dependency-cruiser.cjs

@@ -0,0 +1,31 @@
+// 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.
+
+/** @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"],
+    },
+  },
+};

package/eslint/env-names.js

@@ -0,0 +1,27 @@
+// Environment variables are named by bounded context (krizaka/.github#46): `<CONTEXT>_<THING>`, never after a product
+// (the repository's own, from its package.json, or one a config names) nor a vendor (BUNNY_…, MAILGUN_…) — a vendor is a value (MEDIA_STORAGE_PROVIDER=bunny). The rule
+// `krizaka/env-name` reads `process.env.X`, `process.env["X"]` and `import.meta.env.X`; krizakaBase turns it on.
+
+import { krizakaPlugin } from "./plugin.js";
+
+export { krizakaPlugin } from "./plugin.js";
+export { ENV_PLATFORM_NAMES, ENV_PRODUCT_PREFIXES, ENV_VENDOR_PREFIXES, envNamePrefixProblem, ownProductPrefix } from "./rules.js";
+
+/**
+ * Flat config: `krizaka/env-name` on the given files.
+ * @param {{ files?: string[], products?: string[], vendors?: string[], allow?: string[] }} [options]
+ *   `products`, `vendors`: extra refused prefixes; `allow`: extra names a platform sets.
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export function envNames({ files = ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"], products = [], vendors = [], allow = [] } = {}) {
+  return [
+    {
+      name: "krizaka/env-name",
+      files,
+      plugins: { krizaka: krizakaPlugin },
+      rules: { "krizaka/env-name": ["error", { products, vendors, allow }] },
+    },
+  ];
+}
+
+export default envNames;

package/eslint/index.js

@@ -1,11 +1,13 @@
 // The base flat config of every Krizaka JavaScript repository: @eslint/js and typescript-eslint recommended,
-// the React hooks rules, and a light import ordering (autofixable, a warning).
+// the React hooks rules, a light import ordering (autofixable, a warning) and env names by bounded context.
 import js from "@eslint/js";
 import reactHooks from "eslint-plugin-react-hooks";
 import simpleImportSort from "eslint-plugin-simple-import-sort";
 import globals from "globals";
 import tseslint from "typescript-eslint";
 
+import { envNames } from "./env-names.js";
+
 /** Generated or vendored output, never linted. */
 export const KRIZAKA_IGNORES = Object.freeze([
   "**/node_modules/**",
@@ -43,6 +45,8 @@ export const krizakaCommon = [
       "simple-import-sort/exports": "warn",
     },
   },
+  // Environment variables named by bounded context, never a product or a vendor (krizaka/.github#46).
+  ...envNames(),
 ];
 
 /**

package/eslint/no-locale-ternary.js

@@ -3,37 +3,10 @@
 // shipped as a plugin rule (`krizaka/no-locale-ternary`) so it never collides with a repository's own
 // `no-restricted-syntax` options.
 
-const MESSAGE = "Put the text in the message catalogues (messages/<locale>.json) and read it from the dictionary (t.…).";
+import { krizakaPlugin } from "./plugin.js";
 
-/** The selectors, also usable in `no-restricted-syntax`. */
-export const LOCALE_TERNARY_SELECTORS = Object.freeze([
-  "ConditionalExpression[test.type='BinaryExpression'][test.right.value=/^(fr|en)$/]",
-  "ConditionalExpression > Identifier.test[name=/^(isFr|isEn|fr)$/]",
-]);
-
-/** @type {import("eslint").Rule.RuleModule} */
-const rule = {
-  meta: {
-    type: "problem",
-    docs: { description: "Forbid choosing a text with a locale ternary outside routing code." },
-    schema: [],
-    messages: { localeTernary: MESSAGE },
-  },
-  create(context) {
-    /** @type {Record<string, (node: import("estree").Node) => void>} */
-    const visitors = {};
-    for (const selector of LOCALE_TERNARY_SELECTORS) {
-      visitors[selector] = (node) => context.report({ node, messageId: "localeTernary" });
-    }
-    return visitors;
-  },
-};
-
-/** The plugin carrying the rule. */
-export const krizakaPlugin = {
-  meta: { name: "@krizaka/config" },
-  rules: { "no-locale-ternary": rule },
-};
+export { krizakaPlugin } from "./plugin.js";
+export { LOCALE_TERNARY_SELECTORS } from "./rules.js";
 
 /** Routing files that legitimately compare locales (the krizaka.com layout, a common convention). */
 export const DEFAULT_ROUTING_FILES = Object.freeze([

package/eslint/plugin.js

@@ -0,0 +1,17 @@
+// 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, noFetchInClientEffect, noLocaleTernaryRule, noLocalTableOrForm } from "./rules.js";
+
+/** @type {import("eslint").ESLint.Plugin} */
+export const krizakaPlugin = {
+  meta: { name: "@krizaka/config" },
+  rules: {
+    "no-locale-ternary": noLocaleTernaryRule,
+    "no-fetch-in-client-effect": noFetchInClientEffect,
+    "no-direct-tanstack-import": noDirectTanstackImport,
+    "no-local-table-or-form": noLocalTableOrForm,
+    "env-name": envName,
+  },
+};
+
+export default krizakaPlugin;

package/eslint/rules.js

@@ -0,0 +1,266 @@
+// The rule modules of the `krizaka` ESLint plugin (eslint/plugin.js). Patterns come from ../patterns.js, which the
+// ratchet reads too: a rule and its counter never diverge.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { countFormFields, EFFECT_NAMES_SOURCE, FETCH_NAMES_SOURCE, TANSTACK_SCOPE } from "../patterns.js";
+
+/** @typedef {import("eslint").Rule.RuleModule} RuleModule */
+/** @typedef {import("estree").Node} Node */
+
+/** The selectors of `no-locale-ternary`, also usable in `no-restricted-syntax`. */
+export const LOCALE_TERNARY_SELECTORS = Object.freeze([
+  "ConditionalExpression[test.type='BinaryExpression'][test.right.value=/^(fr|en)$/]",
+  "ConditionalExpression > Identifier.test[name=/^(isFr|isEn|fr)$/]",
+]);
+
+/** @type {RuleModule} */
+export const noLocaleTernaryRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid choosing a text with a locale ternary outside routing code." },
+    schema: [],
+    messages: {
+      localeTernary:
+        "Put the text in the message catalogues (messages/<locale>.json) and read it from the dictionary (t.…).",
+    },
+  },
+  create(context) {
+    /** @type {Record<string, (node: Node) => void>} */
+    const visitors = {};
+    for (const selector of LOCALE_TERNARY_SELECTORS) {
+      visitors[selector] = (node) => context.report({ node, messageId: "localeTernary" });
+    }
+    return visitors;
+  },
+};
+
+/**
+ * True when the file starts with a `"use client"` directive.
+ * @param {import("eslint").Rule.RuleContext} context
+ */
+function isClientFile(context) {
+  for (const statement of context.sourceCode.ast.body) {
+    if (statement.type !== "ExpressionStatement" || !("directive" in statement)) return false;
+    if (statement.directive === "use client") return true;
+  }
+  return false;
+}
+
+const callee = (/** @type {string} */ names) => `:matches([callee.name=/${names}/], [callee.property.name=/${names}/])`;
+
+/** S1: the first screen is a Server Component, the interaction is Query — never a fetch in a client effect. */
+/** @type {RuleModule} */
+export const noFetchInClientEffect = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Forbid a fetch (or krizakaFetch) inside a useEffect of a \"use client\" file." },
+    schema: [],
+    messages: {
+      fetchInEffect:
+        "A fetch in a client effect: render the first screen in a Server Component and read the rest with @krizaka/query (useQuery / useMutation).",
+    },
+  },
+  create(context) {
+    if (!isClientFile(context)) return {};
+    return {
+      [`CallExpression${callee(EFFECT_NAMES_SOURCE)} CallExpression${callee(FETCH_NAMES_SOURCE)}`]: (/** @type {Node} */ node) =>
+        context.report({ node, messageId: "fetchInEffect" }),
+    };
+  },
+};
+
+/** 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])),
+    };
+  },
+};
+
+/** S2, S3: a table is `@krizaka/ui/data-table`, a form is `@krizaka/ui/form` — except a form of a single field. */
+/** @type {RuleModule} */
+export const noLocalTableOrForm = {
+  meta: {
+    type: "suggestion",
+    docs: { description: "Forbid a hand-written <table> or <form> in an app (single-field forms excepted)." },
+    schema: [
+      {
+        type: "object",
+        properties: { maxFormFields: { type: "integer", minimum: 0 } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      table: "A hand-written <table>: use DataTable from @krizaka/ui/data-table.",
+      form: "A hand-written <form> of {{fields}} fields: use createKrizakaForm from @krizaka/ui/form.",
+    },
+  },
+  create(context) {
+    const maxFormFields = context.options[0]?.maxFormFields ?? 1;
+    return {
+      /** @param {any} node JSXOpeningElement */
+      "JSXOpeningElement[name.type='JSXIdentifier']:matches([name.name='table'], [name.name='form'])"(node) {
+        if (node.name.name === "table") return context.report({ node, messageId: "table" });
+        const fields = countFormFields(context.sourceCode.getText(node.parent));
+        if (fields > maxFormFields) context.report({ node, messageId: "form", data: { fields: String(fields) } });
+      },
+    };
+  },
+};
+
+/**
+ * The organisation's name is never a prefix; a repository's own product is found from its package.json (below) and a
+ * config may name more (`products`): a deployment already says which product it is (krizaka/.github#46).
+ */
+export const ENV_PRODUCT_PREFIXES = Object.freeze(["KRIZAKA"]);
+
+/** The bounded contexts a name starts with (krizaka/.github#46). */
+export const ENV_CONTEXT_WORDS = Object.freeze(["APP", "DATABASE", "AUTH", "MEDIA", "MAIL", "PUSH", "PAYMENTS", "REALTIME", "ABUSE", "OBSERVABILITY", "AI", "OPERATOR"]);
+
+/** @type {Map<string, string | null>} */
+const ownProductCache = new Map();
+
+/**
+ * The product a repository is: the first word of the nearest package.json's name, scope removed
+ * (`acme-monorepo` → ACME, `@org/acme-admin` → ACME); null for a one-word name (`@org/realtime`) or a context word.
+ * @param {string} cwd
+ */
+export function ownProductPrefix(cwd) {
+  if (ownProductCache.has(cwd)) return ownProductCache.get(cwd) ?? null;
+  let found = null;
+  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;
+      }
+      break;
+    }
+    if (dirname(dir) === dir) break;
+  }
+  ownProductCache.set(cwd, found);
+  return found;
+}
+
+/** 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",
+  "TURNSTILE", "CLOUDFLARE", "VERCEL", "DIGITALOCEAN", "DO", "AWS", "GCP", "AZURE", "GOOGLE", "FACEBOOK", "APPLE",
+  "GITHUB", "GH", "EXPO", "FIREBASE", "FCM", "APNS", "REDIS", "VALKEY", "OPENAI", "ANTHROPIC", "OLLAMA", "SENTRY",
+  "TWILIO", "SUPABASE", "MAPBOX",
+]);
+
+/** Names the platforms set themselves (GitHub Actions, Vercel, EAS): read, never chosen. */
+export const ENV_PLATFORM_NAMES = Object.freeze([
+  "GITHUB_ACTIONS", "GITHUB_TOKEN", "GITHUB_SHA", "GITHUB_REF", "GITHUB_REF_NAME", "GITHUB_REPOSITORY", "GITHUB_RUN_ID",
+  "GITHUB_RUN_NUMBER", "GITHUB_WORKSPACE", "GITHUB_OUTPUT", "GITHUB_STEP_SUMMARY", "GITHUB_EVENT_NAME", "GITHUB_SERVER_URL",
+  "VERCEL", "VERCEL_ENV", "VERCEL_URL", "VERCEL_GIT_COMMIT_SHA", "EAS_BUILD", "EAS_BUILD_PLATFORM", "EAS_BUILD_PROFILE",
+  "EXPO_TOKEN",
+]);
+
+/** The framework prefixes a client-exposed value needs; the name after them follows the same rule. */
+const PUBLIC_PREFIX = /^(?:NEXT_PUBLIC_|EXPO_PUBLIC_|VITE_)/;
+
+/**
+ * The prefix that makes an environment variable name refused, or null. Exported for scripts and tests.
+ * @param {string} name
+ * @param {{ products?: readonly string[], vendors?: readonly string[], allow?: readonly string[] }} [options]
+ * @returns {{ prefix: string, kind: "product" | "vendor" } | null}
+ */
+export function envNamePrefixProblem(name, { products = ENV_PRODUCT_PREFIXES, vendors = ENV_VENDOR_PREFIXES, allow = ENV_PLATFORM_NAMES } = {}) {
+  if (allow.includes(name)) return null;
+  const bare = name.replace(PUBLIC_PREFIX, "");
+  const head = bare.split("_")[0] ?? "";
+  if (bare === head) return null; // one word (PORT, CI): no prefix to judge
+  if (products.includes(head)) return { prefix: head, kind: "product" };
+  if (vendors.includes(head)) return { prefix: head, kind: "vendor" };
+  return null;
+}
+
+/** The name read by `process.env.X`, `process.env["X"]` or `import.meta.env.X`, or null. */
+function envNameOf(/** @type {any} */ node) {
+  const object = node.object;
+  const isProcessEnv = object?.type === "MemberExpression" && object.object?.type === "Identifier" && object.object.name === "process" && !object.computed && object.property?.name === "env";
+  const isImportMetaEnv = object?.type === "MemberExpression" && object.object?.type === "MetaProperty" && !object.computed && object.property?.name === "env";
+  if (!isProcessEnv && !isImportMetaEnv) return null;
+  if (!node.computed && node.property?.type === "Identifier") return node.property.name;
+  if (node.computed && node.property?.type === "Literal" && typeof node.property.value === "string") return node.property.value;
+  return null;
+}
+
+/**
+ * Environment variables are named by bounded context — `<CONTEXT>_<THING>` (APP_, DATABASE_, AUTH_, MEDIA_, MAIL_,
+ * PUSH_, PAYMENTS_, REALTIME_, ABUSE_, OBSERVABILITY_, AI_, OPERATOR_) — never after a product or a vendor
+ * (krizaka/.github#46). The products refused: the organisation's name and the repository's own (its package.json). Options:
+ * `products`, `vendors` (extra prefixes), `allow` (extra names a platform sets).
+ * @type {RuleModule}
+ */
+export const envName = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid environment variable names prefixed with a product or a vendor (krizaka/.github#46)." },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          products: { type: "array", items: { type: "string" } },
+          vendors: { type: "array", items: { type: "string" } },
+          allow: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      product:
+        "{{name}} is named after a product ({{prefix}}_): name it by its bounded context, <CONTEXT>_<THING> (APP_, DATABASE_, AUTH_, MEDIA_, MAIL_, PUSH_, PAYMENTS_, REALTIME_, ABUSE_, OBSERVABILITY_, AI_, OPERATOR_).",
+      vendor:
+        "{{name}} is named after a vendor ({{prefix}}_): the vendor is a value (<CONTEXT>_PROVIDER={{lower}}) and its settings sit under the context (e.g. MEDIA_STORAGE_API_KEY, MAIL_API_KEY).",
+    },
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const own = ownProductPrefix(context.cwd);
+    const products = [...ENV_PRODUCT_PREFIXES, ...(own && !ENV_VENDOR_PREFIXES.includes(own) ? [own] : []), ...(options.products ?? [])];
+    const vendors = [...ENV_VENDOR_PREFIXES, ...(options.vendors ?? [])];
+    const allow = [...ENV_PLATFORM_NAMES, ...(options.allow ?? [])];
+    return {
+      /** @param {any} node */
+      MemberExpression(node) {
+        const name = envNameOf(node);
+        if (!name) return;
+        const problem = envNamePrefixProblem(name, { products, vendors, allow });
+        if (problem) context.report({ node, messageId: problem.kind, data: { name, prefix: problem.prefix, lower: problem.prefix.toLowerCase() } });
+      },
+    };
+  },
+};

package/eslint/stack.js

@@ -0,0 +1,40 @@
+// 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.
+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",
+]);
+
+/**
+ * Flat config: the three 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[]}
+ */
+export function krizakaStack({
+  files = ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+  ignores = [],
+  severity = "warn",
+  maxFormFields = 1,
+} = {}) {
+  return [
+    {
+      name: "krizaka/stack",
+      files,
+      ...(ignores.length > 0 ? { ignores } : {}),
+      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 }],
+      },
+    },
+  ];
+}
+
+export default krizakaStack;

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@krizaka/config",
-  "version": "0.1.0",
-  "description": "The shared configuration of every Krizaka JavaScript repository: ESLint flat configs (base, Next.js, the four UI rules, no locale ternary), tsconfig bases, Prettier, EditorConfig, and the krizaka-ratchet debt counter.",
+  "version": "0.3.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.",
   "keywords": [
     "krizaka",
     "eslint-config",
     "tsconfig",
     "prettier-config",
     "ratchet",
-    "design-system"
+    "design-system",
+    "dependency-cruiser",
+    "tanstack"
   ],
   "homepage": "https://github.com/krizaka/krizaka-ui/tree/main/packages/config#readme",
   "bugs": "https://github.com/krizaka/krizaka-ui/issues",
@@ -25,6 +27,10 @@
     "./eslint/next": "./eslint/next.js",
     "./eslint/krizaka-ui": "./eslint/krizaka-ui.js",
     "./eslint/no-locale-ternary": "./eslint/no-locale-ternary.js",
+    "./eslint/stack": "./eslint/stack.js",
+    "./eslint/env-names": "./eslint/env-names.js",
+    "./eslint/plugin": "./eslint/plugin.js",
+    "./dependency-cruiser": "./dependency-cruiser.cjs",
     "./patterns": "./patterns.js",
     "./ratchet": "./ratchet/ratchet.js",
     "./prettier": "./prettier.config.js",
@@ -44,6 +50,7 @@
     "ratchet",
     "tsconfig",
     "patterns.js",
+    "dependency-cruiser.cjs",
     "prettier.config.js",
     ".editorconfig",
     "README.md",
@@ -76,6 +83,7 @@
     "@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",
@@ -99,7 +107,7 @@
         "ratchet/ratchet.js",
         "patterns.js"
       ],
-      "limit": "5 kB",
+      "limit": "8 kB",
       "gzip": true
     }
   ],

package/patterns.js

@@ -31,3 +31,87 @@ export const ARBITRARY_VAR_SOURCE = "\\[var\\(--";
 
 /** `className={`…${x}`}` — the ratchet's text approximation of the TemplateLiteral rule. */
 export const CLASSNAME_TEMPLATE_SOURCE = "className=\\{\\s*`";
+
+// ── The stack debts (decisions S1–S3, S11 of the stack ADR) ──────────────────────────────────────────────────────
+// Read by the ESLint rules (eslint/stack.js) and by the ratchet, like the UI patterns above.
+
+/** A `"use client"` directive heading the file (after comments). */
+export const USE_CLIENT_SOURCE = String.raw`^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use client["']`;
+
+/** The opening of an effect call: `useEffect(`, `React.useLayoutEffect(`. */
+export const EFFECT_CALL_SOURCE = String.raw`\buse(?:Layout)?Effect\s*\(`;
+
+/** A fetch call: `fetch(`, `window.fetch(`, `krizakaFetch(` — never `refetch(`. */
+export const FETCH_CALL_SOURCE = String.raw`\b(?:fetch|krizakaFetch)\s*\(`;
+
+/** The names the ESLint rule matches (callee identifier or member property). */
+export const EFFECT_NAMES_SOURCE = "^use(Layout)?Effect$";
+export const FETCH_NAMES_SOURCE = "^(fetch|krizakaFetch)$";
+
+/** The headless engines that only enter through a `@krizaka/*` package. */
+export const TANSTACK_SCOPE = "@tanstack/";
+
+/**
+ * An import of one of the given packages (or scopes ending in `/`): `from "x"`, `import "x"`, `import("x")`,
+ * `require("x")`, `export … from "x"`.
+ * @param {readonly string[]} specifiers package names (`framer-motion`) or scope prefixes (`@tanstack/`)
+ * @returns {string} regex source
+ */
+export function importSource(specifiers) {
+  if (specifiers.length === 0) return "(?!)"; // nothing listed: matches nothing
+  const escape = (/** @type {string} */ s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const names = specifiers.map((s) => (s.endsWith("/") ? `${escape(s)}[^"']+` : `${escape(s)}(?:/[^"']*)?`));
+  return String.raw`(?:\bfrom|\bimport|\brequire)\s*(?:\(\s*)?["'](?:${names.join("|")})["']`;
+}
+
+/** A `<table` or `<form` element written in an app (JSX or HTML). */
+export const TABLE_OR_FORM_SOURCE = String.raw`<(table|form)(?=[\s>/])`;
+
+/** The elements that hold a value in a form: native fields and the field primitives of `@krizaka/ui`. */
+export const FORM_FIELD_TAGS = Object.freeze([
+  "input", "textarea", "select",
+  "Input", "Textarea", "Select", "Combobox", "DatePicker", "DateRangePicker", "TagInput", "Checkbox", "Switch",
+  "RadioGroup", "Slider", "SearchField", "Dropzone", "FileUpload", "OtpInput",
+]);
+
+/** `<input type="hidden|submit|button|reset|image">` holds no value the user types. */
+const NOT_A_FIELD = /\btype=(?:\{\s?)?["'](?:hidden|submit|button|reset|image)["']/;
+
+/**
+ * The value-holding fields inside a form's source text.
+ * @param {string} text
+ * @returns {number}
+ */
+export function countFormFields(text) {
+  const tags = new RegExp(String.raw`<(${FORM_FIELD_TAGS.join("|")})(?=[\s/>])([^>]*)`, "g");
+  let fields = 0;
+  for (const [, tag, attributes] of text.matchAll(tags)) {
+    if (tag === "input" && NOT_A_FIELD.test(attributes ?? "")) continue;
+    fields += 1;
+  }
+  return fields;
+}
+
+/**
+ * The text between the parenthesis that opens at `open` and the one that closes it, skipping strings and comments.
+ * @param {string} source
+ * @param {number} open index of the `(`
+ * @returns {string}
+ */
+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;
+    else if (c === ")" && --depth === 0) return source.slice(open + 1, i);
+  }
+  return source.slice(open + 1);
+}

package/ratchet/ratchet.js

@@ -1,4 +1,4 @@
-// The ratchet: counts the four UI debts in a repository and refuses any increase against lint-ratchet.json.
+// The ratchet: counts the UI and stack debts of a repository and refuses any increase against lint-ratchet.json.
 // 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";
@@ -6,22 +6,59 @@ import { relative, resolve } from "node:path";
 
 import { glob } from "tinyglobby";
 
-import { ARBITRARY_VAR_SOURCE, CLASSNAME_TEMPLATE_SOURCE, LIGHT_VARIANT_SOURCE, paletteSource } from "../patterns.js";
+import {
+  ARBITRARY_VAR_SOURCE,
+  balancedArguments,
+  CLASSNAME_TEMPLATE_SOURCE,
+  countFormFields,
+  EFFECT_CALL_SOURCE,
+  FETCH_CALL_SOURCE,
+  importSource,
+  LIGHT_VARIANT_SOURCE,
+  paletteSource,
+  TABLE_OR_FORM_SOURCE,
+  TANSTACK_SCOPE,
+  USE_CLIENT_SOURCE,
+} from "../patterns.js";
 
 export const RATCHET_FILE = "lint-ratchet.json";
 export const DEFAULT_GLOBS = Object.freeze(["app/**/*.tsx", "components/**/*.tsx", "src/**/*.tsx"]);
+/** The stack counters read every source file: data hooks and fetchers live in .ts too. */
+export const DEFAULT_STACK_GLOBS = Object.freeze(
+  ["app", "components", "src", "lib", "hooks", "features"].map((dir) => `${dir}/**/*.{js,jsx,mjs,ts,tsx,mts}`),
+);
 const IGNORE = ["**/node_modules/**", "**/dist/**", "**/.next/**", "**/storybook-static/**", "**/coverage/**"];
 
-/** @typedef {"palette" | "light" | "arbitraryVar" | "classNameTemplate"} CounterName */
+/** @typedef {"palette" | "light" | "arbitraryVar" | "classNameTemplate"} UiCounterName */
+/** @typedef {"fetchInClientEffect" | "directTanstackImport" | "localTableOrForm" | "retiredImport"} StackCounterName */
+/** @typedef {UiCounterName | StackCounterName} CounterName */
 /** @typedef {Record<CounterName, number>} Counters */
-/** @typedef {{ globs?: string[], allow?: string[], counters: Counters }} RatchetFile */
+/**
+ * @typedef {object} RatchetFile
+ * @property {string[]} [globs] files of the UI counters
+ * @property {string[]} [stackGlobs] files of the stack counters
+ * @property {string[]} [allow] palette families tolerated
+ * @property {string[]} [retire] dependencies on their way out: their imports are counted by `retiredImport`
+ * @property {number} [maxFormFields] a form with at most this many fields is not counted (default 1)
+ * @property {Partial<Counters>} counters
+ */
 
-/** The counters, in report order. */
-export const COUNTERS = /** @type {const} */ (["palette", "light", "arbitraryVar", "classNameTemplate"]);
+/** The UI counters (the four rules of krizakaUi), in report order. */
+export const UI_COUNTERS = /** @type {const} */ (["palette", "light", "arbitraryVar", "classNameTemplate"]);
+/** The stack counters (the three rules of krizakaStack, and the dependencies to retire), in report order. */
+export const STACK_COUNTERS = /** @type {const} */ ([
+  "fetchInClientEffect",
+  "directTanstackImport",
+  "localTableOrForm",
+  "retiredImport",
+]);
+/** Every counter, in report order. */
+export const COUNTERS = /** @type {const} */ ([...UI_COUNTERS, ...STACK_COUNTERS]);
+const zero = () => /** @type {Counters} */ (Object.fromEntries(COUNTERS.map((name) => [name, 0])));
 
 /**
  * @param {string[]} [allow] palette families tolerated (same option as krizakaUi)
- * @returns {Record<CounterName, RegExp>}
+ * @returns {Record<UiCounterName, RegExp>}
  */
 export function counterPatterns(allow = []) {
   return {
@@ -33,33 +70,76 @@ export function counterPatterns(allow = []) {
 }
 
 /**
- * Counts the four debts in one source text.
+ * Counts the four UI debts in one source text.
  * @param {string} source
  * @param {string[]} [allow]
- * @returns {Counters}
+ * @returns {Record<UiCounterName, number>}
  */
 export function countSource(source, allow = []) {
   const patterns = counterPatterns(allow);
-  /** @type {Counters} */
+  /** @type {Record<UiCounterName, number>} */
   const counters = { palette: 0, light: 0, arbitraryVar: 0, classNameTemplate: 0 };
-  for (const name of COUNTERS) counters[name] = source.match(patterns[name])?.length ?? 0;
+  for (const name of UI_COUNTERS) counters[name] = source.match(patterns[name])?.length ?? 0;
   return counters;
 }
 
 /**
- * Counts the debts in every file matched by the globs under `root`.
- * @param {{ root: string, globs?: readonly string[], allow?: string[] }} options
- * @returns {Promise<{ counters: Counters, files: number }>}
+ * Counts the stack debts in one source text: fetch calls inside the effects of a `"use client"` file, imports of
+ * `@tanstack/*`, hand-written tables and forms of more than `maxFormFields` fields, imports of the retired dependencies.
+ * @param {string} source
+ * @param {{ retire?: readonly string[], maxFormFields?: number }} [options]
+ * @returns {Record<StackCounterName, number>}
+ */
+export function countStackSource(source, { retire = [], maxFormFields = 1 } = {}) {
+  let fetchInClientEffect = 0;
+  if (new RegExp(USE_CLIENT_SOURCE).test(source)) {
+    for (const effect of source.matchAll(new RegExp(EFFECT_CALL_SOURCE, "g"))) {
+      const body = balancedArguments(source, (effect.index ?? 0) + effect[0].length - 1);
+      fetchInClientEffect += body.match(new RegExp(FETCH_CALL_SOURCE, "g"))?.length ?? 0;
+    }
+  }
+  let localTableOrForm = 0;
+  for (const element of source.matchAll(new RegExp(TABLE_OR_FORM_SOURCE, "g"))) {
+    if (element[1] === "table") localTableOrForm += 1;
+    else {
+      const end = source.indexOf("</form>", element.index);
+      if (end >= 0 && countFormFields(source.slice(element.index, end)) > maxFormFields) localTableOrForm += 1;
+    }
+  }
+  return {
+    fetchInClientEffect,
+    directTanstackImport: source.match(new RegExp(importSource([TANSTACK_SCOPE]), "g"))?.length ?? 0,
+    localTableOrForm,
+    retiredImport: source.match(new RegExp(importSource(retire), "g"))?.length ?? 0,
+  };
+}
+
+/**
+ * Counts the debts under `root`: the UI counters in the files of `globs`, the stack counters in those of `stackGlobs`.
+ * @param {{ root: string, globs?: readonly string[], stackGlobs?: readonly string[], allow?: string[],
+ *   retire?: readonly string[], maxFormFields?: number }} options
+ * @returns {Promise<{ counters: Counters, files: number, stackFiles: number }>}
  */
-export async function countRepository({ root, globs = DEFAULT_GLOBS, allow = [] }) {
+export async function countRepository({
+  root,
+  globs = DEFAULT_GLOBS,
+  stackGlobs = DEFAULT_STACK_GLOBS,
+  allow = [],
+  retire = [],
+  maxFormFields = 1,
+}) {
   const files = await glob([...globs], { cwd: root, ignore: IGNORE, absolute: true });
-  /** @type {Counters} */
-  const counters = { palette: 0, light: 0, arbitraryVar: 0, classNameTemplate: 0 };
+  const stackFiles = await glob([...stackGlobs], { cwd: root, ignore: IGNORE, absolute: true });
+  const counters = zero();
   for (const file of files) {
     const found = countSource(readFileSync(file, "utf8"), allow);
-    for (const name of COUNTERS) counters[name] += found[name];
+    for (const name of UI_COUNTERS) counters[name] += found[name];
   }
-  return { counters, files: files.length };
+  for (const file of stackFiles) {
+    const found = countStackSource(readFileSync(file, "utf8"), { retire, maxFormFields });
+    for (const name of STACK_COUNTERS) counters[name] += found[name];
+  }
+  return { counters, files: files.length, stackFiles: stackFiles.length };
 }
 
 /**
@@ -69,7 +149,10 @@ export async function countRepository({ root, globs = DEFAULT_GLOBS, allow = []
 function readRatchet(path) {
   const data = JSON.parse(readFileSync(path, "utf8"));
   for (const name of COUNTERS) {
-    if (!Number.isInteger(data?.counters?.[name]) || data.counters[name] < 0) {
+    const value = data?.counters?.[name];
+    // a stack counter may be missing from a file written before it existed: --update records it
+    if (value === undefined && STACK_COUNTERS.includes(/** @type {StackCounterName} */ (name))) continue;
+    if (!Number.isInteger(value) || value < 0) {
       throw new RatchetError(`${path}: counters.${name} must be a non-negative integer.`);
     }
   }
@@ -92,19 +175,23 @@ export class RatchetError extends Error {}
  * @property {boolean} ok no counter above its recorded value
  * @property {"check" | "init" | "update"} mode
  * @property {string} file the ratchet file, relative to root
- * @property {number} files source files scanned
+ * @property {number} files source files scanned by the UI counters
+ * @property {number} stackFiles source files scanned by the stack counters
  * @property {string[]} globs
+ * @property {string[]} stackGlobs
  * @property {Record<CounterName, { recorded: number, current: number, delta: number }>} counters
  * @property {CounterName[]} increased
  * @property {CounterName[]} decreased
- * @property {boolean} written the ratchet file was created or lowered
+ * @property {CounterName[]} added counters missing from the file (recorded at their current value by --update)
+ * @property {boolean} written the ratchet file was created, lowered or completed
  */
 
 /**
  * Runs the ratchet.
  * - `check` (default): fails when a counter is above its recorded value.
  * - `init`: creates the file with the current counters (refuses to overwrite one).
- * - `update`: lowers each recorded value to the current one, never raises it (still fails on an increase).
+ * - `update`: lowers each recorded value to the current one, never raises it (still fails on an increase), and records
+ *   the counters the file does not have yet at their current value.
  * @param {{ root: string, mode?: "check" | "init" | "update", globs?: string[], file?: string }} options
  * @returns {Promise<RatchetResult>}
  */
@@ -116,9 +203,20 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
 
   const recordedFile = exists ? readRatchet(path) : undefined;
   const useGlobs = globs && globs.length > 0 ? globs : (recordedFile?.globs ?? [...DEFAULT_GLOBS]);
+  const stackGlobs = recordedFile?.stackGlobs ?? [...DEFAULT_STACK_GLOBS];
   const allow = recordedFile?.allow ?? [];
-  const { counters: current, files } = await countRepository({ root, globs: useGlobs, allow });
-  const recorded = recordedFile?.counters ?? current;
+  const retire = recordedFile?.retire ?? [];
+  const maxFormFields = recordedFile?.maxFormFields ?? 1;
+  const { counters: current, files, stackFiles } = await countRepository({
+    root,
+    globs: useGlobs,
+    stackGlobs,
+    allow,
+    retire,
+    maxFormFields,
+  });
+  /** @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} */ ({});
@@ -133,13 +231,12 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
 
   let written = false;
   if (mode === "init") {
-    writeRatchet(path, { globs: useGlobs, ...(allow.length > 0 ? { allow } : {}), counters: current });
+    writeRatchet(path, { globs: useGlobs, stackGlobs, ...(allow.length > 0 ? { allow } : {}), counters: current });
     written = true;
-  } else if (mode === "update" && decreased.length > 0 && recordedFile) {
-    /** @type {Counters} */
-    const lowered = { ...recordedFile.counters };
+  } else if (mode === "update" && (decreased.length > 0 || added.length > 0) && recordedFile) {
+    const lowered = zero();
     for (const name of COUNTERS) lowered[name] = Math.min(recorded[name], current[name]);
-    writeRatchet(path, { ...recordedFile, counters: lowered });
+    writeRatchet(path, { ...recordedFile, stackGlobs: recordedFile.stackGlobs ?? stackGlobs, counters: lowered });
     for (const name of decreased) report[name].recorded = lowered[name];
     written = true;
   }
@@ -150,10 +247,13 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
     mode,
     file: shown.startsWith("..") ? path : shown,
     files,
+    stackFiles,
     globs: useGlobs,
+    stackGlobs,
     counters: report,
     increased,
     decreased,
+    added,
     written,
   };
 }