@krizaka/config 0.10.0 → 0.11.1

package/README.md

@@ -97,6 +97,15 @@ read any file (a Vite/Tauri app has no `"use client"`).
 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`.
 
+### Cognitive complexity (Sonar S3776)
+
+On 2026-10-27 every failed quality gate came from Sonar's S3776 (krizaka/.github#319), and only Sonar checked it.
+`krizakaStack()` now carries **`sonarjs/cognitive-complexity` at 15** (`eslint-plugin-sonarjs`; the threshold is never
+raised, the rule never disabled): split the function (early returns, extracted helpers, a lookup table instead of a
+chain of `if`). **Error by default** (`complexity: "error"`); a repository with debt passes `complexity: "warn"` while
+`krizaka-ratchet` (`cognitiveComplexity`) freezes the count of functions over 15 at `--update` time and fails any
+increase. Test files (`*.test.*`, `*.spec.*`, `__tests__/`) are not counted, as Sonar does not scan them.
+
 ### 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
@@ -229,6 +238,7 @@ npx krizaka-ratchet --json      # in CI: the same check, machine-readable
 | `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 |
+| `cognitiveComplexity` | functions whose `sonarjs/cognitive-complexity` is above 15 (Sonar S3776), counted by running the rule on each source file of `stackGlobs`, tests excluded; the KPI of the cognitive debt, it only goes down |
 | `routeStateSelection` | a Tabs / chip group / choice grid / segmented switch (incl. `RadioGroup.Root variant="segmented"`) / toggle group of a view driven by local state (`value`, `defaultValue`, `onValueChange`) without `routeKey`, and without `// @ephemeral: <reason>`: the URL is the state |
 
 The UI counters scan `app/**/*.tsx`, `components/**/*.tsx` and `src/**/*.tsx` by default (`node_modules`, `dist`,

package/bin/krizaka-ratchet.mjs

@@ -8,12 +8,12 @@ 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,
-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
+data loaded in an effect, state derived in an effect, direct @tanstack/* imports, hand-written tables and forms, functions above Sonar's cognitive complexity of 15 (S3776), 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), record the new ones
+  --update   lower the recorded counters to the current values (never raises them), record the new ones, keep the counters it does not know
   --json     machine-readable report on stdout (for CI)
   --root     repository root (default: current directory)
   --file     ratchet file name (default: lint-ratchet.json)`;
@@ -30,6 +30,7 @@ const LABELS = {
   localTableOrForm: "hand-written tables / forms",
   retiredImport: "imports of retired deps",
   routeStateSelection: "selections in local state (not the URL)",
+  cognitiveComplexity: "functions over complexity 15 (S3776)",
 };
 
 let args;
@@ -81,6 +82,9 @@ try {
     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}.`);
     else if (result.added.length > 0) console.log(`New counters (${result.added.join(", ")}): run krizaka-ratchet --update and commit ${result.file}.`);
+    if (result.unmeasured.length > 0) {
+      console.log(`  ! not measured by this version, kept as recorded: ${result.unmeasured.join(", ")}`);
+    }
     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.`,

package/eslint/stack.js

@@ -2,8 +2,13 @@
 // @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 sonarjs from "eslint-plugin-sonarjs";
+
 import { krizakaPlugin } from "./plugin.js";
 
+/** Sonar S3776 threshold: a function above it is a quality-gate failure. Never raised. */
+export const COGNITIVE_COMPLEXITY_MAX = 15;
+
 /** The rule names, as configured. */
 export const STACK_RULES = Object.freeze([
   "krizaka/no-fetch-in-client-effect",
@@ -12,13 +17,16 @@ export const STACK_RULES = Object.freeze([
   "krizaka/no-local-table-or-form",
   "krizaka/no-family-switcher",
   "krizaka/route-state-selection",
+  "sonarjs/cognitive-complexity",
 ]);
 
 /**
  * Flat config: the stack rules on an app's sources.
- * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", effects?: "warn" | "error" | "off", maxFormFields?: number }} [options]
+ * @param {{ files?: string[], ignores?: string[], severity?: "warn" | "error", effects?: "warn" | "error" | "off", complexity?: "warn" | "error", 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.
+ *   `complexity`: severity of `sonarjs/cognitive-complexity` (Sonar S3776, threshold 15): `"error"` by default; a
+ *   repository with debt passes `"warn"` while `krizaka-ratchet` (`cognitiveComplexity`) freezes the count and fails any increase.
  *   `maxFormFields`: a form with at most this many fields is allowed (default 1 — a search box, a newsletter).
  * @returns {import("eslint").Linter.Config[]}
  */
@@ -27,6 +35,7 @@ export function krizakaStack({
   ignores = [],
   severity = "warn",
   effects = "error",
+  complexity = "error",
   maxFormFields = 1,
 } = {}) {
   return [
@@ -34,7 +43,7 @@ export function krizakaStack({
       name: "krizaka/stack",
       files,
       ...(ignores.length > 0 ? { ignores } : {}),
-      plugins: { krizaka: krizakaPlugin },
+      plugins: { krizaka: krizakaPlugin, sonarjs },
       rules: {
         "krizaka/no-fetch-in-client-effect": severity,
         // useEffect is for the outside world: data is useQuery/useMutation, derived state is computed in render.
@@ -45,6 +54,8 @@ export function krizakaStack({
         "krizaka/no-family-switcher": "error",
         // A selection of a view (tabs, segmented, toggles, chip groups) lives in the URL, not in local state.
         "krizaka/route-state-selection": severity,
+        // Sonar S3776 at lint time (krizaka/.github#319): split the function, never raise the threshold.
+        "sonarjs/cognitive-complexity": [complexity, COGNITIVE_COMPLEXITY_MAX],
       },
     },
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/config",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -72,6 +72,7 @@
     "dependency-cruiser": "^18.6.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-simple-import-sort": "^14.0.0",
+    "eslint-plugin-sonarjs": "^4.2.2",
     "globals": "^17.13.0",
     "tinyglobby": "^0.2.17",
     "typescript-eslint": "^8.71.1"

package/ratchet/ratchet.js

@@ -2,9 +2,12 @@
 // 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 { isAbsolute, relative, resolve } from "node:path";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
+import { Linter } from "eslint";
+import sonarjs from "eslint-plugin-sonarjs";
 import { glob } from "tinyglobby";
+import tseslint from "typescript-eslint";
 
 import {
   ARBITRARY_VAR_SOURCE,
@@ -34,7 +37,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" | "asyncInEffect" | "derivedStateInEffect" | "directTanstackImport" | "localTableOrForm" | "retiredImport" | "routeStateSelection"} StackCounterName */
+/** @typedef {"fetchInClientEffect" | "asyncInEffect" | "derivedStateInEffect" | "directTanstackImport" | "localTableOrForm" | "retiredImport" | "routeStateSelection" | "cognitiveComplexity"} StackCounterName */
 /** @typedef {UiCounterName | StackCounterName} CounterName */
 /** @typedef {Record<CounterName, number>} Counters */
 /**
@@ -58,9 +61,13 @@ export const STACK_COUNTERS = /** @type {const} */ ([
   "localTableOrForm",
   "retiredImport",
   "routeStateSelection",
+  "cognitiveComplexity",
 ]);
 /** Every counter, in report order. */
 export const COUNTERS = /** @type {const} */ ([...UI_COUNTERS, ...STACK_COUNTERS]);
+/** Sonar S3776's threshold (same value as eslint/stack.js COGNITIVE_COMPLEXITY_MAX). Never raised. */
+const COMPLEXITY_MAX = 15;
+const TEST_FILE = /(\.(test|spec)\.[cm]?[jt]sx?$)|(\/__tests__\/)/;
 const zero = () => /** @type {Counters} */ (Object.fromEntries(COUNTERS.map((name) => [name, 0])));
 
 /**
@@ -95,7 +102,7 @@ export function countSource(source, allow = []) {
  * `@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>}
+ * @returns {Record<Exclude<StackCounterName, "cognitiveComplexity">, number>} (cognitiveComplexity: countCognitiveComplexity, it needs the file name)
  */
 export function countStackSource(source, { retire = [], maxFormFields = 1 } = {}) {
   let fetchInClientEffect = 0;
@@ -133,6 +140,32 @@ export function countStackSource(source, { retire = [], maxFormFields = 1 } = {}
   };
 }
 
+/**
+ * Counts the functions above Sonar's cognitive-complexity threshold (S3776) in one source text, with the same
+ * `sonarjs/cognitive-complexity` rule the ESLint preset uses. A file that does not parse counts for 0 (ESLint reports it).
+ * @param {string} source
+ * @param {string} [filename]
+ * @returns {number}
+ */
+export function countCognitiveComplexity(source, filename = "file.tsx") {
+  const messages = complexityLinter().verify(source, COMPLEXITY_CONFIG, { filename: `file${extname(filename)}` });
+  return messages.filter((/** @type {{ ruleId: string | null }} */ m) => m.ruleId === "sonarjs/cognitive-complexity").length;
+}
+
+/** One Linter for the whole run: building it (and the parser) per file made the CLI 10x slower in CI. */
+/** @type {Linter | undefined} */
+let sharedLinter;
+const complexityLinter = () => (sharedLinter ??= new Linter());
+/** @type {any} */
+const COMPLEXITY_CONFIG = [
+  {
+    files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+    languageOptions: { parser: /** @type {any} */ (tseslint.parser) },
+    plugins: { sonarjs },
+    rules: { "sonarjs/cognitive-complexity": ["error", COMPLEXITY_MAX] },
+  },
+];
+
 /**
  * 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[],
@@ -155,8 +188,10 @@ export async function countRepository({
     for (const name of UI_COUNTERS) counters[name] += found[name];
   }
   for (const file of stackFiles) {
-    const found = countStackSource(readFileSync(file, "utf8"), { retire, maxFormFields });
-    for (const name of STACK_COUNTERS) counters[name] += found[name];
+    const found = /** @type {Partial<Counters>} */ (countStackSource(readFileSync(file, "utf8"), { retire, maxFormFields }));
+    for (const name of STACK_COUNTERS) counters[name] += found[name] ?? 0;
+    // Sonar scans the product code, not its tests
+    if (!TEST_FILE.test(file)) counters.cognitiveComplexity += countCognitiveComplexity(readFileSync(file, "utf8"), file);
   }
   return { counters, files: files.length, stackFiles: stackFiles.length };
 }
@@ -202,6 +237,7 @@ export class RatchetError extends Error {}
  * @property {CounterName[]} increased
  * @property {CounterName[]} decreased
  * @property {CounterName[]} added counters missing from the file (recorded at their current value by --update)
+ * @property {string[]} unmeasured counters of the file this version does not measure: kept as recorded by --update, never dropped
  * @property {boolean} written the ratchet file was created, lowered or completed
  */
 
@@ -260,6 +296,8 @@ 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 {string[]} */
+  const unmeasured = Object.keys(recordedFile?.counters ?? {}).filter((n) => !COUNTERS.includes(/** @type {CounterName} */ (n)));
 
   const { report, increased, decreased } = compareCounters(current, recorded);
 
@@ -270,7 +308,9 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
   } 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, stackGlobs: recordedFile.stackGlobs ?? stackGlobs, counters: lowered });
+    // a counter this version does not measure (a repository's own, or a newer preset's) is kept as recorded, never dropped
+    const counters = { ...lowered, ...Object.fromEntries(unmeasured.map((name) => [name, /** @type {Record<string, number>} */ (recordedFile?.counters)?.[name]])) };
+    writeRatchet(path, { ...recordedFile, stackGlobs: recordedFile.stackGlobs ?? stackGlobs, counters });
     for (const name of decreased) report[name].recorded = lowered[name];
     written = true;
   }
@@ -288,6 +328,7 @@ export async function runRatchet({ root, mode = "check", globs, file = RATCHET_F
     increased,
     decreased,
     added,
+    unmeasured,
     written,
   };
 }