@krizaka/config 0.0.0-stage → 0.2.0

package/eslint/no-locale-ternary.js

@@ -0,0 +1,41 @@
+// A component never chooses its text with `locale === "fr" ? … : …`: every user-facing string lives in the
+// message catalogues. Only routing code compares locales. Same selectors as the rule in force on krizaka.com,
+// shipped as a plugin rule (`krizaka/no-locale-ternary`) so it never collides with a repository's own
+// `no-restricted-syntax` options.
+
+import { krizakaPlugin } from "./plugin.js";
+
+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([
+  "**/proxy.ts",
+  "**/middleware.ts",
+  "**/i18n.ts",
+  "**/seo.ts",
+  "**/app/[[]locale[]]/layout.tsx",
+  "**/I18nProvider.tsx",
+]);
+
+/**
+ * Flat config: `krizaka/no-locale-ternary` on the given files, except routing code.
+ * @param {{ files?: string[], routing?: string[] }} [options] `routing`: files allowed to compare locales.
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export function noLocaleTernary({
+  files = ["**/*.{js,jsx,ts,tsx}"],
+  routing = [...DEFAULT_ROUTING_FILES],
+} = {}) {
+  return [
+    {
+      name: "krizaka/no-locale-ternary",
+      files,
+      ignores: routing,
+      plugins: { krizaka: krizakaPlugin },
+      rules: { "krizaka/no-locale-ternary": "error" },
+    },
+  ];
+}
+
+export default noLocaleTernary;

package/eslint/plugin.js

@@ -0,0 +1,16 @@
+// 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 { 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,
+  },
+};
+
+export default krizakaPlugin;

package/eslint/rules.js

@@ -0,0 +1,129 @@
+// 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 { 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) } });
+      },
+    };
+  },
+};

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,6 +1,120 @@
 {
   "name": "@krizaka/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+    "dependency-cruiser",
+    "tanstack"
+  ],
+  "homepage": "https://github.com/krizaka/krizaka-ui/tree/main/packages/config#readme",
+  "bugs": "https://github.com/krizaka/krizaka-ui/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krizaka/krizaka-ui.git",
+    "directory": "packages/config"
+  },
+  "license": "Apache-2.0",
+  "author": "Krizaka (https://www.krizaka.com)",
+  "type": "module",
+  "exports": {
+    "./eslint": "./eslint/index.js",
+    "./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/plugin": "./eslint/plugin.js",
+    "./dependency-cruiser": "./dependency-cruiser.cjs",
+    "./patterns": "./patterns.js",
+    "./ratchet": "./ratchet/ratchet.js",
+    "./prettier": "./prettier.config.js",
+    "./tsconfig/base.json": "./tsconfig/base.json",
+    "./tsconfig/react-library.json": "./tsconfig/react-library.json",
+    "./tsconfig/next.json": "./tsconfig/next.json",
+    "./tsconfig/react-native.json": "./tsconfig/react-native.json",
+    "./editorconfig": "./.editorconfig",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "krizaka-ratchet": "./bin/krizaka-ratchet.mjs"
+  },
+  "files": [
+    "bin",
+    "eslint",
+    "ratchet",
+    "tsconfig",
+    "patterns.js",
+    "dependency-cruiser.cjs",
+    "prettier.config.js",
+    ".editorconfig",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@eslint/js": "^9.39.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "globals": "^17.13.0",
+    "tinyglobby": "^0.2.17",
+    "typescript-eslint": "^8.71.1"
+  },
+  "peerDependencies": {
+    "eslint": "^9",
+    "eslint-config-next": ">=16",
+    "prettier": "^3",
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "eslint-config-next": {
+      "optional": true
+    },
+    "prettier": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@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",
+    "prettier": "^3.9.9",
+    "publint": "^0.3.25",
+    "size-limit": "^14.2.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "size-limit": [
+    {
+      "name": "krizaka-ratchet",
+      "path": [
+        "bin/krizaka-ratchet.mjs",
+        "ratchet/ratchet.js",
+        "patterns.js"
+      ],
+      "limit": "8 kB",
+      "gzip": true
+    }
+  ],
+  "scripts": {
+    "lint": "eslint . --max-warnings 0 && tsc --noEmit --noUnusedLocals --noUnusedParameters --noFallthroughCasesInSwitch --noImplicitReturns",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "size": "size-limit",
+    "publint": "publint"
+  }
 }

package/patterns.js

@@ -0,0 +1,117 @@
+// The four debts the UI refactor removes, as regex sources. One definition, read by the ESLint rules
+// (eslint/krizaka-ui.js, on className literals) and by the ratchet (bin/krizaka-ratchet.mjs, on the source text).
+
+/** Tailwind palette families a product never writes: a component reads a role (bg-surface-1, text-accent…). */
+export const PALETTE_FAMILIES = Object.freeze([
+  "zinc", "slate", "gray", "neutral", "stone",
+  "fuchsia", "violet", "purple", "pink", "rose",
+  "emerald", "green", "amber", "yellow", "red",
+  "blue", "sky", "cyan", "indigo",
+]);
+
+/** Utilities that take a colour. */
+export const COLOR_UTILITIES = Object.freeze(["bg", "text", "border", "from", "via", "to", "ring", "shadow", "fill", "stroke"]);
+
+/**
+ * `bg-zinc-900`, `text-violet-400/80`… — a raw palette step.
+ * @param {readonly string[]} [allow] families allowed for documented, isolated cases (e.g. `["emerald"]`).
+ * @returns {string} regex source
+ */
+export function paletteSource(allow = []) {
+  const families = PALETTE_FAMILIES.filter((family) => !allow.includes(family));
+  if (families.length === 0) return "(?!)"; // everything allowed: matches nothing
+  return `\\b(${COLOR_UTILITIES.join("|")})-(${families.join("|")})-[0-9]`;
+}
+
+/** `light:bg-white` — a theme is a set of tokens, never a variant. */
+export const LIGHT_VARIANT_SOURCE = "\\blight:";
+
+/** `bg-[var(--surface-1)]` — the variable has a utility in @krizaka/tailwind. */
+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/prettier.config.js

@@ -0,0 +1,15 @@
+// The Krizaka Prettier config: `export { default } from "@krizaka/config/prettier";` in prettier.config.js.
+/** @type {import("prettier").Config} */
+const config = {
+  printWidth: 120,
+  singleQuote: false,
+  jsxSingleQuote: false,
+  trailingComma: "all",
+  semi: true,
+  tabWidth: 2,
+  useTabs: false,
+  arrowParens: "always",
+  endOfLine: "lf",
+};
+
+export default config;