@krizaka/config 0.9.1 → 0.10.0

package/README.md

@@ -54,6 +54,7 @@ the package.
 | `@krizaka/config/dependency-cruiser` | The shared dependency-cruiser config, generated from the covered-domains map: one `krizaka-first-<domain>` rule per domain (dates, i18n, query, icons, ui), `no-circular`, `not-to-unresolvable`, `not-to-dev-dep`. `.withOptions({ exemptFrom })` for a monorepo whose own packages are the facades. |
 | `@krizaka/config/covered-domains` · `/covered-domains.json` | The covered-domains map (one data file) and its helpers: the message, the patterns, the Markdown table of « Use Krizaka first ». |
 | `krizaka-known-violations` (bin) · `@krizaka/config/known-violations` | The known violations of dependency-cruiser, which only shrink, see below. |
+| `krizaka-server-client-boundary` (bin) · `@krizaka/config/server-client-boundary` | Fails when a server-rendered module imports a function from a `"use client"` `@krizaka/*` module (React #441), see below. |
 | `@krizaka/config/tsconfig/*.json` | `base` (strict, ES2022, bundler resolution), `react-library` (+ DOM, `react-jsx`), `next` (+ the Next plugin, `noEmit`, `incremental`), `react-native` (`jsx: react-native`, `customConditions`; with Expo: `"extends": ["expo/tsconfig.base", "@krizaka/config/tsconfig/react-native.json"]`). |
 | `@krizaka/config/prettier` · `.editorconfig` | The formatting. |
 | `krizaka-ratchet` (bin) | The debt counter, see below. |
@@ -170,6 +171,21 @@ stays only for repositories that have not moved yet.
 `noLocaleTernary({ files, routing })`: `routing` lists the files allowed to compare locales (default: `proxy.ts`,
 `middleware.ts`, `i18n.ts`, `seo.ts`, `app/[locale]/layout.tsx`, `I18nProvider.tsx`).
 
+### Server/client boundary (`krizaka-server-client-boundary`)
+
+A Next.js server module that calls a function exported by a `"use client"` module (`readFilterParams()` of
+`@krizaka/ui/filter-bar`) crashes the page with React error #441. Unit tests ignore the directive and `next build` does not
+see it. Every Next.js App Router app runs the guard in its lint:
+
+```sh
+krizaka-server-client-boundary                 # from the app's folder: reads app/ or src/app/ and the "@/*" alias of tsconfig.json
+krizaka-server-client-boundary --root apps/web --app app --scope @krizaka
+```
+
+It walks the pages, layouts and routes, then every local module they import, and stops at a `"use client"` file. A lowercase
+value import (a function, a hook, a constant) from a client module of the scope is an offence; components and `import type`
+are fine. Render a component, or move the function to a plain module. `checkBoundary()` is also exported for a test.
+
 ### Environment variable names (`krizaka/env-name`)
 
 Environment variables are named by bounded context (krizaka/.github#46): `<CONTEXT>_<THING>` with CONTEXT one of

package/bin/krizaka-server-client-boundary.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// krizaka-server-client-boundary: no server-rendered module calls a function exported by a "use client" Krizaka module (React #441).
+import { checkBoundary, DEFAULT_SCOPE } from "../ratchet/server-client-boundary.js";
+
+const USAGE = `Usage: krizaka-server-client-boundary [--root <app folder>] [--app <app router folder>] [--alias <folder of "@/">] [--scope ${DEFAULT_SCOPE}]
+
+Walks what the server renders (pages, layouts, routes and the local modules they import, down to a "use client" file) and fails
+when one imports a function (a lowercase export) from a "use client" module of the scope: the server would call a client
+reference and the page would crash (React error #441). Render a component, or move the function to a plain module.`;
+
+const options = {};
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === "--root") options.root = args[++i];
+  else if (arg === "--app") options.appDir = args[++i];
+  else if (arg === "--alias") options.alias = args[++i];
+  else if (arg === "--scope") options.scope = args[++i];
+  else {
+    console.error(USAGE);
+    process.exit(2);
+  }
+}
+try {
+  const { seen, offences } = checkBoundary(options);
+  if (offences.length === 0) {
+    console.log(`krizaka-server-client-boundary: ${seen.size} server modules checked, no client function called from the server.`);
+  } else {
+    console.error(`krizaka-server-client-boundary: ${offences.length} server module(s) import a function from a "use client" module (React #441):`);
+    for (const line of offences) console.error(`  ${line}`);
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/config",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "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",
@@ -36,6 +36,7 @@
     "./covered-domains": "./covered-domains.cjs",
     "./covered-domains.json": "./covered-domains.json",
     "./known-violations": "./ratchet/known-violations.js",
+    "./server-client-boundary": "./ratchet/server-client-boundary.js",
     "./patterns": "./patterns.js",
     "./ratchet": "./ratchet/ratchet.js",
     "./prettier": "./prettier.config.js",
@@ -48,7 +49,8 @@
   },
   "bin": {
     "krizaka-ratchet": "./bin/krizaka-ratchet.mjs",
-    "krizaka-known-violations": "./bin/krizaka-known-violations.mjs"
+    "krizaka-known-violations": "./bin/krizaka-known-violations.mjs",
+    "krizaka-server-client-boundary": "./bin/krizaka-server-client-boundary.mjs"
   },
   "files": [
     "bin",

package/ratchet/server-client-boundary.js

@@ -0,0 +1,187 @@
+// The server/client boundary of a Next.js app (App Router): a module the server renders must not call a function that a
+// `"use client"` module of a Krizaka package exports. Next replaces such an export with a client reference, and calling it on the
+// server crashes the page with React error #441 ("Attempted to call readFilterParams() from the server"). Unit tests never see
+// it (vitest ignores the directive) and `next build` does not either, so this walks what the server renders: the pages, layouts
+// and routes, then every local module they import, stopping at a `"use client"` file.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+export const DEFAULT_SCOPE = "@krizaka";
+const ENTRY = /(?:^|[\\/])(?:page|layout|route|error|global-error|loading|not-found|default|template)\.(?:ts|tsx|js|jsx|mjs)$/;
+// `import … from "x"` / `export … from "x"`: the clause is everything up to the first quote (no nested quantifier: linear).
+const STATEMENT = /(?:^|\n)[ \t]*(import|export)\b([^"';]*)["']([^"']+)["']/g;
+const EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs"];
+
+/** @param {string} dir @returns {string[]} */
+const walk = (dir) =>
+  readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (name === "node_modules" || name === ".next") return [];
+    return statSync(path).isDirectory() ? walk(path) : [path];
+  });
+
+/** @param {string} path */
+/** Does the module start with the `"use client"` directive (comments and blank lines may come first)? Scanned, not matched: linear. @param {string} source */
+export const isClientSource = (source) => {
+  let i = 0;
+  for (;;) {
+    while (i < source.length && /\s/.test(source[i])) i++;
+    if (source.startsWith("/*", i)) {
+      const end = source.indexOf("*/", i + 2);
+      if (end < 0) return false;
+      i = end + 2;
+    } else if (source.startsWith("//", i)) {
+      const end = source.indexOf("\n", i);
+      if (end < 0) return false;
+      i = end + 1;
+    } else break;
+  }
+  const quote = source[i];
+  return (quote === '"' || quote === "'") && source.startsWith("use client", i + 1) && source[i + 11] === quote;
+};
+
+/** @param {string} path */
+const isFile = (path) => existsSync(path) && statSync(path).isFile();
+
+/** The `"@/*"` alias of tsconfig.json (read as text: comments and trailing commas are fine); `@/` means the root when there is none. */
+/** @param {string} root */
+export const readAlias = (root) => {
+  try {
+    const text = readFileSync(join(root, "tsconfig.json"), "utf8");
+    const key = text.indexOf('"@/*"');
+    const open = key < 0 ? -1 : text.indexOf('"', text.indexOf("[", key) + 1);
+    const target = open < 0 ? "" : text.slice(open + 1, text.indexOf('"', open + 1));
+    if (target) return target.replace(/\/?\*$/, "") || ".";
+  } catch {
+    // no tsconfig, or one we cannot read: the default stands
+  }
+  return ".";
+};
+
+/** The first folder of `candidates` that exists under root. */
+/** @param {string} root */
+const findApp = (root) => ["app", "src/app"].map((d) => join(root, d)).find((d) => existsSync(d));
+
+/** @param {string} root @param {string} aliasDir @param {string} from @param {string} spec @returns {string | null} */
+const resolveLocal = (root, aliasDir, from, spec) => {
+  let base = null;
+  if (spec.startsWith("@/")) base = join(root, aliasDir, spec.slice(2));
+  else if (spec.startsWith(".")) base = resolve(dirname(from), spec);
+  if (!base) return null;
+  for (const ext of EXTENSIONS) if (isFile(base + ext)) return base + ext;
+  for (const index of ["index.ts", "index.tsx", "index.js"]) if (isFile(join(base, index))) return join(base, index);
+  return null;
+};
+
+/** @param {string} from @param {string} scope @param {string} name @returns {string | null} */
+const findPackageDir = (from, scope, name) => {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", scope, name);
+    if (existsSync(candidate)) return candidate;
+    if (dirname(dir) === dir) return null;
+  }
+};
+
+/** @param {unknown} target @returns {string | null} */
+const pick = (target) => {
+  if (typeof target === "string") return target;
+  if (!target || typeof target !== "object") return null;
+  for (const key of ["import", "module", "default", "node", "require"]) {
+    const found = pick(/** @type {Record<string, unknown>} */ (target)[key]);
+    if (found) return found;
+  }
+  return null;
+};
+
+/** Is the module `spec` of a package a `"use client"` module? Reads the first line of the built entry its `exports` names. */
+/** @param {string} root @param {string} spec */
+export const packageIsClient = (root, spec) => {
+  const [scope, name, ...rest] = spec.split("/");
+  const dir = findPackageDir(root, scope, name);
+  if (!dir) return false;
+  let file;
+  try {
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    const key = rest.length ? `./${rest.join("/")}` : ".";
+    file = pick(manifest.exports?.[key]) ?? (rest.length ? null : manifest.module ?? manifest.main);
+  } catch {
+    return false;
+  }
+  if (!file) return false;
+  const entry = join(dir, file);
+  return isFile(entry) && isClientSource(readFileSync(entry, "utf8"));
+};
+
+/**
+ * The lowercase (function-like) names a statement's clause brings in as values; a type-only import is erased and harmless.
+ * `clause` is the text between `import`/`export` and the quote of the module, e.g. ` { a, type B } from `.
+ * @param {string} clause
+ * @returns {string[]}
+ */
+export const functionNames = (clause) => {
+  const words = clause.trim().split(/\s+/);
+  if (words.at(-1) === "from") words.pop();
+  const text = words.join(" ");
+  if (text.startsWith("type ") || text.startsWith("type{")) return [];
+  const open = text.indexOf("{");
+  const close = open < 0 ? -1 : text.indexOf("}", open);
+  const names = open < 0 ? [] : bracedNames(text.slice(open + 1, close < 0 ? text.length : close));
+  const head = defaultImportName(open < 0 ? text : `${text.slice(0, open)} ${close < 0 ? "" : text.slice(close + 1)}`);
+  if (head) names.push(head);
+  return names;
+};
+
+/** The function-like names inside the braces of an import clause (`type X` entries are erased). @param {string} braces @returns {string[]} */
+const bracedNames = (braces) =>
+  braces
+    .split(",")
+    .map((part) => part.trim().split(" "))
+    .filter((tokens) => tokens[0] && !(tokens[0] === "type" && tokens.length > 1) && /^[a-z_$]/.test(tokens[0]))
+    .map((tokens) => tokens[0]);
+
+/** The default import of what is left outside the braces, when it is function-like: `import readIt from "@krizaka/x"`. @param {string} rest @returns {string | null} */
+const defaultImportName = (rest) => {
+  const head = rest.replaceAll(",", " ").trim().split(" ")[0] ?? "";
+  return head && !head.startsWith("*") && /^[a-z_$]/.test(head) ? head : null;
+};
+
+/**
+ * Walk what the server renders. `appDirs` defaults to `app` or `src/app`.
+ * Returns the visited files and the offences (`file imports a, b from @krizaka/x ("use client")`).
+ */
+/** @param {{ root?: string, appDir?: string, alias?: string, scope?: string }} [options] @returns {{ seen: Set<string>, offences: string[] }} */
+export const checkBoundary = ({ root = process.cwd(), appDir, alias, scope = DEFAULT_SCOPE } = {}) => {
+  const app = appDir ? resolve(root, appDir) : findApp(root);
+  if (!app) throw new Error(`No app folder under ${root} (looked for app and src/app); pass --app.`);
+  const aliasDir = alias ?? readAlias(root);
+  /** @type {Set<string>} */
+  const seen = new Set();
+  /** @type {string[]} */
+  const offences = [];
+  const clientCache = new Map();
+  /** @param {string} spec */
+  const isClient = (spec) => {
+    if (!clientCache.has(spec)) clientCache.set(spec, packageIsClient(root, spec));
+    return clientCache.get(spec);
+  };
+  /** @param {string} file */
+  const visit = (file) => {
+    if (seen.has(file)) return;
+    seen.add(file);
+    const source = readFileSync(file, "utf8");
+    if (isClientSource(source)) return;
+    for (const match of source.matchAll(STATEMENT)) {
+      const [, , clause, spec] = match;
+      if (!clause.trimEnd().endsWith("from")) continue; // `import "x"`, or a string in some other statement
+      if (spec.startsWith(`${scope}/`)) {
+        const names = functionNames(clause);
+        if (names.length && isClient(spec)) offences.push(`${relative(root, file)} imports ${names.join(", ")} from ${spec} ("use client")`);
+        continue;
+      }
+      const local = resolveLocal(root, aliasDir, file, spec);
+      if (local && /\.(?:ts|tsx|js|jsx|mjs)$/.test(local)) visit(local);
+    }
+  };
+  for (const entry of walk(app).filter((f) => ENTRY.test(f) && !/\.(?:test|spec)\./.test(f))) visit(entry);
+  return { seen, offences };
+};