@krizaka/config 0.8.1 → 0.9.1

package/README.md

@@ -83,7 +83,20 @@ Flat config replaces a rule's options instead of concatenating them: a repositor
 `no-restricted-syntax` merges both lists with `krizakaUiRestrictedSyntax()`. `no-locale-ternary` is a plugin rule for
 that reason — it composes with anything.
 
-### The stack rules
+### The effect rules (react-effects)
+
+[`useEffect` is for the outside world](https://github.com/krizaka/.github/blob/main/docs/standards/react-effects.md)
+(Oussama, 2026-10-27). Two rules of `krizakaStack()`, **errors by default** (`effects: "error"`); a repository with debt
+passes `effects: "warn"` while `krizaka-ratchet` (`asyncInEffect`, `derivedStateInEffect`) brings the count to 0. They
+read any file (a Vite/Tauri app has no `"use client"`).
+
+1. **`krizaka/no-async-in-effect`** — an effect that awaits, calls `.then(`, `fetch(`, `invoke(`, `api.*` or `*Client.*`:
+   read with `useQuery`, write with `useMutation` (`@krizaka/query`), keyed by the selection. A subscribe-and-cleanup
+   effect (`listen(`, `addEventListener(`, `subscribe(`, `WebSocket`… plus a `return`) is never reported.
+2. **`krizaka/no-derived-state-in-effect`** — an effect whose only statements are `setX(…)` calls: compute the value
+   during render, or reset the component with a `key`.
+
+### The three stack rules
 
 From [ADR-001](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
@@ -195,6 +208,8 @@ npx krizaka-ratchet --json      # in CI: the same check, machine-readable
 | `arbitraryVar` | `\[var\(--` |
 | `classNameTemplate` | `` className=\{\s*` `` |
 | `fetchInClientEffect` | in a file opening with `"use client"`: `fetch(` / `krizakaFetch(` between the parentheses of a `useEffect(` / `useLayoutEffect(` |
+| `asyncInEffect` | an effect (`useEffect(` / `useLayoutEffect(`, any file) whose callback awaits or calls `.then(`, `fetch(`, `invoke(`, `api.*`, `*Client.*`, and is not a subscribe-and-cleanup |
+| `derivedStateInEffect` | an effect whose only statements are `setX(…)` calls (optionally under `if`) |
 | `directTanstackImport` | `from` / `import` / `import(` / `require(` of `"@tanstack/…"` |
 | `localTableOrForm` | `<table`, and `<form` … `</form>` holding more fields than `maxFormFields` (default 1) |
 | `retiredImport` | an import of a dependency listed in `retire` (e.g. `["framer-motion"]`): the way out of a dependency |

package/bin/krizaka-ratchet.mjs

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

package/eslint/plugin.js

@@ -1,6 +1,6 @@
 // The `krizaka` ESLint plugin: one object carrying every rule, so that configs registering it compose (flat config
 // refuses two different objects under the same plugin name).
-import { envName, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
+import { envName, noAsyncInEffect, noDerivedStateInEffect, noFamilySwitcher, noFetchInClientEffect, noLightVariant, noLocaleTernaryRule, noLocalTableOrForm, noRawPalette,routeStateSelection } from "./rules.js";
 
 /** @type {import("eslint").ESLint.Plugin} */
 export const krizakaPlugin = {
@@ -8,6 +8,8 @@ export const krizakaPlugin = {
   rules: {
     "no-locale-ternary": noLocaleTernaryRule,
     "no-fetch-in-client-effect": noFetchInClientEffect,
+    "no-async-in-effect": noAsyncInEffect,
+    "no-derived-state-in-effect": noDerivedStateInEffect,
     "no-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 } from "../patterns.js";
+import { countFormFields, EFFECT_NAMES_SOURCE, effectProblem, FETCH_NAMES_SOURCE, isLocalSelection, LIGHT_VARIANT_SOURCE, paletteSource } from "../patterns.js";
 
 /** @typedef {import("eslint").Rule.RuleModule} RuleModule */
 /** @typedef {import("estree").Node} Node */
@@ -70,6 +70,52 @@ export const noFetchInClientEffect = {
   },
 };
 
+/**
+ * Reports the effects (`useEffect` / `useLayoutEffect`) whose callback `effectProblem` says is `kind`.
+ * @param {import("eslint").Rule.RuleContext} context
+ * @param {"async" | "derived"} kind
+ * @param {string} messageId
+ */
+function effectVisitor(context, kind, messageId) {
+  return {
+    [`CallExpression${callee(EFFECT_NAMES_SOURCE)}`]: (/** @type {import("estree").CallExpression} */ node) => {
+      const fn = node.arguments[0];
+      if (fn?.type !== "ArrowFunctionExpression" && fn?.type !== "FunctionExpression") return;
+      if (effectProblem(context.sourceCode.getText(fn.body)) === kind) context.report({ node, messageId });
+    },
+  };
+}
+
+/** Oussama, 2026-10-27: async data is `useQuery` / `useMutation`, never an effect (standard: react-effects). */
+/** @type {RuleModule} */
+export const noAsyncInEffect = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid loading data (await, .then, fetch, invoke, api.*, *Client.*) in a useEffect that is not a subscription." },
+    schema: [],
+    messages: {
+      asyncInEffect:
+        "Data is not loaded in an effect: read it with useQuery and write it with useMutation (@krizaka/query), keyed by the selection so a stale answer is dropped. An effect is for a subscription (with its cleanup) or an object URL. See krizaka/.github docs/standards/react-effects.md.",
+    },
+  },
+  create: (context) => effectVisitor(context, "async", "asyncInEffect"),
+};
+
+/** Oussama, 2026-10-27: syncing React state is computed in render, never an effect (standard: react-effects). */
+/** @type {RuleModule} */
+export const noDerivedStateInEffect = {
+  meta: {
+    type: "problem",
+    docs: { description: "Forbid a useEffect whose only statements are setState calls (derive the value in render, or reset with a key)." },
+    schema: [],
+    messages: {
+      derivedState:
+        "An effect that only sets state from props or state renders twice: compute the value during render, or reset the component with a `key`. See krizaka/.github docs/standards/react-effects.md.",
+    },
+  },
+  create: (context) => effectVisitor(context, "derived", "derivedState"),
+};
+
 /** 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 = {

package/eslint/stack.js

@@ -7,6 +7,8 @@ import { krizakaPlugin } from "./plugin.js";
 /** The rule names, as configured. */
 export const STACK_RULES = Object.freeze([
   "krizaka/no-fetch-in-client-effect",
+  "krizaka/no-async-in-effect",
+  "krizaka/no-derived-state-in-effect",
   "krizaka/no-local-table-or-form",
   "krizaka/no-family-switcher",
   "krizaka/route-state-selection",
@@ -14,7 +16,9 @@ export const STACK_RULES = Object.freeze([
 
 /**
  * Flat config: the stack rules on an app's sources.
- * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", maxFormFields?: number }} [options]
+ * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", effects?: "warn" | "error" | "off", maxFormFields?: number }} [options]
+ *   `effects`: severity of the two effect rules (react-effects standard): `"error"` by default; a repository with debt
+ *   passes `"warn"` while `krizaka-ratchet` (asyncInEffect, derivedStateInEffect) brings the count to 0.
  *   `maxFormFields`: a form with at most this many fields is allowed (default 1 — a search box, a newsletter).
  * @returns {import("eslint").Linter.Config[]}
  */
@@ -22,6 +26,7 @@ export function krizakaStack({
   files = ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
   ignores = [],
   severity = "warn",
+  effects = "error",
   maxFormFields = 1,
 } = {}) {
   return [
@@ -32,6 +37,9 @@ export function krizakaStack({
       plugins: { krizaka: krizakaPlugin },
       rules: {
         "krizaka/no-fetch-in-client-effect": severity,
+        // useEffect is for the outside world: data is useQuery/useMutation, derived state is computed in render.
+        "krizaka/no-async-in-effect": effects,
+        "krizaka/no-derived-state-in-effect": effects,
         "krizaka/no-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,6 +1,6 @@
 {
   "name": "@krizaka/config",
-  "version": "0.8.1",
+  "version": "0.9.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",
@@ -115,7 +115,7 @@
         "ratchet/ratchet.js",
         "patterns.js"
       ],
-      "limit": "9 kB",
+      "limit": "12.5 kB",
       "gzip": true
     }
   ],

package/patterns.js

@@ -48,6 +48,149 @@ export const FETCH_CALL_SOURCE = String.raw`\b(?:fetch|krizakaFetch)\s*\(`;
 export const EFFECT_NAMES_SOURCE = "^use(Layout)?Effect$";
 export const FETCH_NAMES_SOURCE = "^(fetch|krizakaFetch)$";
 
+// ── Effects are for the outside world (Oussama, 2026-10-27: « bug à adresser partout ») ─────────────────────────────
+// Standard: krizaka/.github docs/standards/react-effects.md. Read by the rules `krizaka/no-async-in-effect` and
+// `krizaka/no-derived-state-in-effect` (eslint/rules.js) and by the ratchet, through `effectProblem`.
+
+/** What makes an effect load data: an await, `.then(`, `fetch(`, a Tauri `invoke(`, `api.x(`, `fooClient.x(`. */
+export const ASYNC_EFFECT_SOURCE = String.raw`\bawait\b|\.then\s*\(|\b(?:fetch|krizakaFetch|invoke)\s*\(|\bapi\.\w+|\b\w*Client\.\w+\s*\(`;
+
+/** A subscription to a system that pushes events: its callback may be async, the cleanup undoes it. */
+export const SUBSCRIBE_EFFECT_SOURCE = String.raw`\b(?:listen|once|on|addEventListener|subscribe|addListener|new\s+(?:WebSocket|EventSource|ResizeObserver|IntersectionObserver|MutationObserver|BroadcastChannel)|\w+\.on|\w+\.on[A-Z]\w*)\s*(?:<[^()]*>)?\s*\(`;
+
+/**
+ * Text with its strings, template literals and comments blanked (same length), so a keyword in a string is not read.
+ * @param {string} source
+ * @returns {string}
+ */
+export function blankStrings(source) {
+  let out = "";
+  let i = 0;
+  while (i < source.length) {
+    const [blanked, next] = blankedAt(source, i);
+    out += blanked;
+    i = next;
+  }
+  return out;
+}
+
+/**
+ * What `source` holds at `i` once blanked, and where the text goes on: a string or template literal keeps its quotes, a
+ * comment is spaces (newlines kept), any other character is itself.
+ * @param {string} source
+ * @param {number} i
+ * @returns {[string, number]}
+ */
+function blankedAt(source, i) {
+  const c = source[i];
+  if (c === '"' || c === "'" || c === "`") {
+    let j = i + 1;
+    for (; j < source.length && source[j] !== c; j += 1) if (source[j] === "\\") j += 1;
+    return [c + " ".repeat(Math.max(0, j - i - 1)) + c, j + 1];
+  }
+  if (c === "/" && source[i + 1] === "/") {
+    const end = source.indexOf("\n", i);
+    const stop = end < 0 ? source.length : end;
+    return [" ".repeat(stop - i), stop];
+  }
+  if (c === "/" && source[i + 1] === "*") {
+    const end = source.indexOf("*/", i + 2);
+    const stop = end < 0 ? source.length : end + 2;
+    return [source.slice(i, stop).replace(/[^\n]/g, " "), stop];
+  }
+  return [c ?? "", i + 1];
+}
+
+/**
+ * An effect callback without its signature (`() =>`, `async () =>`, `function () `, `cb =>`): what is left is its body.
+ * Scanned, not matched by a regular expression, so no input makes it slow.
+ * @param {string} callback
+ * @returns {string}
+ */
+function withoutSignature(callback) {
+  let i = 0;
+  const skipSpace = () => {
+    while (i < callback.length && /\s/.test(/** @type {string} */ (callback[i]))) i += 1;
+  };
+  skipSpace();
+  if (callback.startsWith("async", i) && /\s/.test(callback[i + 5] ?? "")) {
+    i += 5;
+    skipSpace();
+  }
+  const isFunction = callback.startsWith("function", i);
+  if (isFunction) {
+    i += 8;
+    while (i < callback.length && callback[i] !== "(") i += 1;
+  }
+  if (callback[i] === "(") {
+    const close = callback.indexOf(")", i);
+    if (close < 0) return callback;
+    i = close + 1;
+  } else if (!isFunction) {
+    while (i < callback.length && /\w/.test(/** @type {string} */ (callback[i]))) i += 1;
+  }
+  const afterParams = i;
+  skipSpace();
+  if (callback.startsWith("=>", i)) return callback.slice(i + 2);
+  return isFunction ? callback.slice(afterParams) : callback;
+}
+
+/**
+ * The callback of an effect call without the dependency array that follows it (`cb, [a, b]`).
+ * @param {string} args the balanced arguments of `useEffect(…)`
+ * @returns {string}
+ */
+export function withoutDependencyArray(args) {
+  let end = args.trimEnd();
+  if (end.endsWith(",")) end = end.slice(0, -1).trimEnd();
+  if (!end.endsWith("]")) return args;
+  const open = end.lastIndexOf("[");
+  if (open < 0) return args;
+  const before = end.slice(0, open).trimEnd();
+  return before.endsWith(",") ? before.slice(0, -1) : args;
+}
+
+/**
+ * Removes every `setX(…)` call (balanced) from a blanked text.
+ * @param {string} text
+ * @returns {{ rest: string, found: number }}
+ */
+function withoutSetStateCalls(text) {
+  let out = "";
+  let found = 0;
+  const re = /\bset[A-Z]\w*\s*\(/g;
+  let last = 0;
+  for (let m = re.exec(text); m; m = re.exec(text)) {
+    const open = m.index + m[0].length - 1;
+    const inner = balancedArguments(text, open);
+    out += text.slice(last, m.index);
+    last = open + inner.length + 2;
+    re.lastIndex = last;
+    found += 1;
+  }
+  return { rest: out + text.slice(last), found };
+}
+
+/**
+ * What an effect body is wrong about: `"async"` (it loads data — use `useQuery` / `useMutation`) or `"derived"` (its
+ * only statements are `setX(…)` calls — compute the value in render, or reset with a `key`), else null.
+ * A subscribe-and-cleanup effect (a push source and a `return` that undoes it) is the legitimate use and is never wrong.
+ * @param {string} body the text of the effect callback (with or without its braces)
+ * @returns {"async" | "derived" | null}
+ */
+export function effectProblem(body) {
+  // the ratchet passes the whole callback (`() => { … }`), the ESLint rule its body: strip the signature
+  const text = withoutSignature(blankStrings(body));
+  // an expression body (`() => session.onChange(…)`) returns its cleanup as well as a block that says `return`
+  const returnsCleanup = /\breturn\b/.test(text) || !/^\s*\{/.test(text);
+  if (new RegExp(SUBSCRIBE_EFFECT_SOURCE).test(text) && returnsCleanup) return null;
+  if (new RegExp(ASYNC_EFFECT_SOURCE).test(text)) return "async";
+  const { rest, found } = withoutSetStateCalls(text);
+  if (found === 0) return null;
+  const leftover = rest.replace(/\b(?:if|else)\b/g, "").replace(/\([^()]*(?:\([^()]*\)[^()]*)*\)/g, "").replace(/[\s;{}]/g, "");
+  return leftover === "" ? "derived" : null;
+}
+
 /** The headless engines that only enter through a `@krizaka/*` package. */
 export const TANSTACK_SCOPE = "@tanstack/";
 

package/ratchet/ratchet.js

@@ -12,6 +12,7 @@ import {
   CLASSNAME_TEMPLATE_SOURCE,
   countFormFields,
   EFFECT_CALL_SOURCE,
+  effectProblem,
   FETCH_CALL_SOURCE,
   importSource,
   isLocalSelection,
@@ -21,6 +22,7 @@ import {
   TABLE_OR_FORM_SOURCE,
   TANSTACK_SCOPE,
   USE_CLIENT_SOURCE,
+  withoutDependencyArray,
 } from "../patterns.js";
 
 export const RATCHET_FILE = "lint-ratchet.json";
@@ -32,7 +34,7 @@ export const DEFAULT_STACK_GLOBS = Object.freeze(
 const IGNORE = ["**/node_modules/**", "**/dist/**", "**/.next/**", "**/storybook-static/**", "**/coverage/**"];
 
 /** @typedef {"palette" | "light" | "arbitraryVar" | "classNameTemplate"} UiCounterName */
-/** @typedef {"fetchInClientEffect" | "directTanstackImport" | "localTableOrForm" | "retiredImport" | "routeStateSelection"} StackCounterName */
+/** @typedef {"fetchInClientEffect" | "asyncInEffect" | "derivedStateInEffect" | "directTanstackImport" | "localTableOrForm" | "retiredImport" | "routeStateSelection"} StackCounterName */
 /** @typedef {UiCounterName | StackCounterName} CounterName */
 /** @typedef {Record<CounterName, number>} Counters */
 /**
@@ -50,6 +52,8 @@ export const UI_COUNTERS = /** @type {const} */ (["palette", "light", "arbitrary
 /** The stack counters (the three rules of krizakaStack, and the dependencies to retire), in report order. */
 export const STACK_COUNTERS = /** @type {const} */ ([
   "fetchInClientEffect",
+  "asyncInEffect",
+  "derivedStateInEffect",
   "directTanstackImport",
   "localTableOrForm",
   "retiredImport",
@@ -101,6 +105,15 @@ export function countStackSource(source, { retire = [], maxFormFields = 1 } = {}
       fetchInClientEffect += body.match(new RegExp(FETCH_CALL_SOURCE, "g"))?.length ?? 0;
     }
   }
+  // react-effects standard: every effect (client file or not — a Vite/Tauri app has no directive) is read once
+  let asyncInEffect = 0;
+  let derivedStateInEffect = 0;
+  for (const effect of source.matchAll(new RegExp(EFFECT_CALL_SOURCE, "g"))) {
+    const body = balancedArguments(source, (effect.index ?? 0) + effect[0].length - 1);
+    const problem = effectProblem(withoutDependencyArray(body)); // the dependency array is not the callback
+    if (problem === "async") asyncInEffect += 1;
+    else if (problem === "derived") derivedStateInEffect += 1;
+  }
   let localTableOrForm = 0;
   for (const element of source.matchAll(new RegExp(TABLE_OR_FORM_SOURCE, "g"))) {
     if (element[1] === "table") localTableOrForm += 1;
@@ -111,6 +124,8 @@ export function countStackSource(source, { retire = [], maxFormFields = 1 } = {}
   }
   return {
     fetchInClientEffect,
+    asyncInEffect,
+    derivedStateInEffect,
     directTanstackImport: source.match(new RegExp(importSource([TANSTACK_SCOPE]), "g"))?.length ?? 0,
     localTableOrForm,
     retiredImport: source.match(new RegExp(importSource(retire), "g"))?.length ?? 0,