@zedtech/zedkit-quality 0.3.2 → 0.5.0

package/README.md

@@ -14,7 +14,8 @@ pnpm add -D @zedtech/zedkit-quality
 ```
 
 Peer dependencies (`eslint`, `eslint-plugin-jsx-a11y`,
-`eslint-plugin-better-tailwindcss`) install alongside it.
+`eslint-plugin-better-tailwindcss`, `typescript-eslint`) install
+alongside it.
 
 ## Usage
 
@@ -52,9 +53,12 @@ subagents, commands) see `@zedtech/zedkit-ai` instead.
 ## API
 
 - `uiPreset({ entryPoint })` — flat-config blocks for `.tsx`/`.jsx`:
-  jsx-a11y recommended, Tailwind hygiene, tokens-only classes, no `style`
-  attributes, no raw `try`/`catch`. `entryPoint` (your Tailwind CSS
-  entry) is required: it is the one thing that varies per repo.
+  jsx-a11y recommended, Tailwind hygiene, tokens-only classes (no
+  `w-[13px]` / `gap-[0.75rem]`; Radix `w-[var(--radix-*)]` stays), no `style`
+  attributes, no `forwardRef` (ref is a prop; see `packages/ui/src/button.tsx`),
+  no explicit `any`, files ≤ 300 lines and functions ≤ 60, no raw `try`/`catch`.
+  `entryPoint` (your Tailwind CSS entry) is required: it is the one thing
+  that varies per repo.
 - `defineLayers({ kitPackage, viewDirs, dataDirs, actionPatterns, extraPatterns })` —
   `no-restricted-imports` blocks for routes -> views -> data: the UI kit
   is only imported from views, views never import data clients or
@@ -62,6 +66,11 @@ subagents, commands) see `@zedtech/zedkit-ai` instead.
   `{ kitScope?, viewData?, dataUi? }`) merges your own bans into each
   block — use it instead of a second `no-restricted-imports` block,
   which would replace these per flat-config key semantics.
+- `defineLayers({ preset: "feature-folders", kitPackage, featureRoot })` —
+  same helper, feature-folder mapping: UI imports ports (not adapters),
+  adapters are injected at the composition root, model is pure. Bans
+  apply only under `featureRoot`. Live example:
+  `apps/docs/features/note-list` (running at `/examples/note-list`).
 - `@zedtech/zedkit-quality/tsconfig` — the strict base (`strict`,
   `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`,
   `noUnusedLocals`, and more). Extend it, do not copy it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zedtech/zedkit-quality",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -60,14 +60,16 @@
   "peerDependencies": {
     "eslint": "9.39.5",
     "eslint-plugin-better-tailwindcss": "4.10.0",
-    "eslint-plugin-jsx-a11y": "6.10.2"
+    "eslint-plugin-jsx-a11y": "6.10.2",
+    "typescript-eslint": "8.72.0"
   },
   "devDependencies": {
     "eslint": "9.39.5",
     "eslint-plugin-better-tailwindcss": "4.10.0",
     "eslint-plugin-jsx-a11y": "6.10.2",
     "typescript": "5.9.3",
-    "vitest": "2.1.9"
+    "typescript-eslint": "8.72.0",
+    "vitest": "5.0.5"
   },
   "scripts": {
     "test": "vitest run",

package/src/eslint.d.mts

@@ -15,25 +15,40 @@ export interface RestrictedImportPattern {
   readonly allowTypeImports?: boolean;
 }
 
-export interface DefineLayersOptions {
-  /** UI kit specifier (e.g. `@acme/ui`). */
-  readonly kitPackage: string;
-  /** Minimatch globs for view folders. */
-  readonly viewDirs: readonly string[];
-  /** Minimatch globs for data-access folders. */
-  readonly dataDirs: readonly string[];
-  /** Import specifiers for data clients and server actions. May be empty. */
-  readonly actionPatterns: readonly string[];
-  /**
-   * Consumer bans merged into each block's own patterns (flat-config
-   * rules replace per key, so a consumer block setting
-   * `no-restricted-imports` would otherwise drop these).
-   */
-  readonly extraPatterns?: {
-    readonly kitScope?: readonly RestrictedImportPattern[];
-    readonly viewData?: readonly RestrictedImportPattern[];
-    readonly dataUi?: readonly RestrictedImportPattern[];
-  };
-}
+export type DefineLayersOptions =
+  | {
+      readonly preset?: undefined;
+      /** UI kit specifier (e.g. `@acme/ui`). */
+      readonly kitPackage: string;
+      /** Minimatch globs for view folders. */
+      readonly viewDirs: readonly string[];
+      /** Minimatch globs for data-access folders. */
+      readonly dataDirs: readonly string[];
+      /** Import specifiers for data clients and server actions. May be empty. */
+      readonly actionPatterns: readonly string[];
+      /**
+       * Consumer bans merged into each block's own patterns (flat-config
+       * rules replace per key, so a consumer block setting
+       * `no-restricted-imports` would otherwise drop these).
+       */
+      readonly extraPatterns?: {
+        readonly kitScope?: readonly RestrictedImportPattern[];
+        readonly viewData?: readonly RestrictedImportPattern[];
+        readonly dataUi?: readonly RestrictedImportPattern[];
+      };
+    }
+  | {
+      readonly preset: "feature-folders";
+      /** UI kit specifier (e.g. `@acme/ui`). */
+      readonly kitPackage: string;
+      /** Feature-folder root (e.g. `features`). Bans apply only under this tree. */
+      readonly featureRoot: string;
+      readonly extraPatterns?: {
+        readonly kitScope?: readonly RestrictedImportPattern[];
+        readonly viewData?: readonly RestrictedImportPattern[];
+        readonly dataUi?: readonly RestrictedImportPattern[];
+        readonly model?: readonly RestrictedImportPattern[];
+      };
+    };
 
 export function defineLayers(options: DefineLayersOptions): Linter.Config[];

package/src/eslint.mjs

@@ -1,17 +1,21 @@
-// Shareable UI lint preset: enforces docs/frontend-charter.md by tools.
+// Shareable UI lint preset: charter rule ids live in docs/frontend-charter.md;
+// the messages below carry the explanation.
 //
 // What it enforces on every .tsx/.jsx file:
 // - jsx-a11y recommended (labels, keyboard, focus, ARIA)
 // - Tailwind class hygiene (order, no duplicates, no conflicts, no unknown)
 // - Tokens only: no raw palette colors (bg-red-500), no arbitrary hex/rgb
-//   colors, no raw px font sizes — use the semantic theme tokens
-// - No `style` attributes; no raw try/catch (use a tryCatch wrapper)
+//   colors, no raw px font sizes, no arbitrary px/rem in className
+//   (w-[13px], gap-[0.75rem]) — use the semantic theme tokens
+// - No `style` attributes; no forwardRef (ref is a prop); no explicit `any`;
+//   files ≤ 300 lines, functions ≤ 60; no raw try/catch (use a tryCatch wrapper)
 //
 // Consumer setup (no copy: install the package, pass your Tailwind entry):
 //   `import { uiPreset } from "@zedtech/zedkit-quality"` then
 //   `export default [...uiPreset({ entryPoint: "./app/globals.css" })]`.
 import jsxA11y from "eslint-plugin-jsx-a11y";
 import betterTailwindcss from "eslint-plugin-better-tailwindcss";
+import { plugin as tsPlugin } from "typescript-eslint";
 
 const PALETTE =
   "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|fuchsia|pink|rose";
@@ -57,36 +61,76 @@ export function uiPreset({ entryPoint }) {
               {
                 pattern: `(^|:)(${COLOR_UTILS})-(${PALETTE}|white|black)(-|/|$)`,
                 message:
-                  "Raw palette colors are banned. Use a semantic theme token (see docs/frontend-charter.md).",
+                  "tokens-color: raw palette classes (bg-red-500) are banned. Use a semantic token (background, foreground, primary, destructive, …) so light and dark stay in sync.",
               },
               {
                 pattern: "\\[(#|rgb|hsl)",
                 message:
-                  "Arbitrary color values are banned. Use a semantic theme token (see docs/frontend-charter.md).",
+                  "tokens-color: arbitrary hex/rgb/hsl colors are banned. Use a semantic token (background, foreground, primary, …).",
               },
               {
                 pattern: "text-\\[[^\\]]*px",
-                message: "Raw px font sizes are banned. Use the type scale (see docs/frontend-charter.md).",
+                message:
+                  "tokens-style: raw px font sizes are banned. Use the type scale (text-xs … text-2xl).",
+              },
+              // Radix CSS variables (w-[var(--radix-popover-trigger-width)])
+              // are not matched: they are not a px/rem literal. Overlays
+              // must follow the trigger size. Hardcoded colours are already
+              // tokens-color (palette + hex/rgb/hsl).
+              {
+                pattern: "\\[[0-9.]+(?:px|rem)\\]",
+                message:
+                  "tokens-arbitrary: raw px/rem in className (w-[13px], gap-[0.75rem]) are banned — use the spacing scale (w-4, gap-3) or the type scale (text-sm).",
               },
             ],
           },
         ],
         // NOTE: flat-config rules replace (not merge) by key, so this block
         // restates the root TryStatement ban alongside the style-attribute
-        // ban; without the restatement, .tsx files would lose the ban.
+        // and forwardRef bans; without the restatement, .tsx files would lose them.
         "no-restricted-syntax": [
           "error",
           {
             selector: "TryStatement",
-            message: "Raw try/catch is banned. Use tryCatch/tryCatchAsync from @zedtech/zedkit-core.",
+            message:
+              "try-catch: raw try/catch is banned. Use tryCatch/tryCatchAsync from @zedtech/zedkit-core so thrown values become Error with cause.",
           },
           {
             selector: 'JSXAttribute[name.name="style"]',
-            message: "Inline style attributes are banned. Use theme tokens (see docs/frontend-charter.md).",
+            message:
+              "tokens-style: inline style attributes are banned. Use theme tokens and utility classes.",
+          },
+          {
+            selector: "Identifier[name='forwardRef']",
+            message:
+              "ui-ref: forwardRef is banned. Pass ref as a prop on ComponentProps<\"button\"> (see packages/ui/src/button.tsx).",
           },
         ],
       },
     },
+    {
+      name: "zedkit/ui-types",
+      files: ["**/*.tsx", "**/*.jsx"],
+      plugins: { "@typescript-eslint": tsPlugin },
+      rules: {
+        "@typescript-eslint/no-explicit-any": "error",
+      },
+    },
+    {
+      name: "zedkit/ui-size",
+      files: ["**/*.tsx", "**/*.jsx"],
+      ignores: ["**/*.test.*", "**/*.spec.*", "**/tests/**", "**/__tests__/**"],
+      rules: {
+        "max-lines": [
+          "error",
+          { max: 300, skipBlankLines: true, skipComments: true },
+        ],
+        "max-lines-per-function": [
+          "error",
+          { max: 60, skipBlankLines: true, skipComments: true, IIFEs: true },
+        ],
+      },
+    },
   ];
 }
 
@@ -109,6 +153,18 @@ function asFiles(patterns) {
   });
 }
 
+function assertExtraPatterns(extraPatterns, keys) {
+  const want = keys.join(", ").replace(/, ([^,]+)$/, " or $1");
+  for (const [key, value] of Object.entries(extraPatterns)) {
+    if (!keys.includes(key)) {
+      throw new Error(`defineLayers: unknown extraPatterns key "${key}" (want ${want})`);
+    }
+    if (!Array.isArray(value)) {
+      throw new Error(`defineLayers: extraPatterns.${key} must be a list of no-restricted-imports pattern objects`);
+    }
+  }
+}
+
 /**
  * Route/view/data layer boundaries as `no-restricted-imports` blocks.
  * Dependencies run one way (routes -> views -> data):
@@ -116,30 +172,29 @@ function asFiles(patterns) {
  * - views receive data as props and never import data clients or actions;
  * - data files import no UI (no React runtime, no UI kit).
  *
- * @param {{ kitPackage: string, viewDirs: string[], dataDirs: string[], actionPatterns: string[], extraPatterns?: { kitScope?: object[], viewData?: object[], dataUi?: object[] } }} options
- * - `kitPackage`: UI kit specifier (e.g. `@acme/ui`).
- * - `viewDirs`: view folders (e.g. `app/ui/**`) or file globs.
- * - `dataDirs`: data-access folders or file globs, same shapes.
- * - `actionPatterns`: import specifiers for data clients and server actions.
- *   May be empty (views legitimately import data): the view ban is
- *   then omitted, and the view block is dropped when it would carry
- *   no bans at all.
- * - `extraPatterns`: consumer bans merged into each block's own
- *   patterns (flat-config rules replace per key, so a consumer block
- *   setting `no-restricted-imports` would otherwise drop these).
- *   Keys: `kitScope`, `viewData`, `dataUi`; each a list of standard
- *   `no-restricted-imports` pattern objects, passed through untouched.
+ * @param {object} options
+ * - Classic: `{ kitPackage, viewDirs, dataDirs, actionPatterns, extraPatterns? }`.
+ *   `actionPatterns` may be empty (views legitimately import data): the
+ *   view ban is then omitted, and the view block is dropped when it
+ *   would carry no bans at all. `extraPatterns` merges consumer bans
+ *   into each block (keys: `kitScope`, `viewData`, `dataUi`).
+ * - Preset `feature-folders`: `{ preset: "feature-folders", kitPackage,
+ *   featureRoot, extraPatterns? }`. UI may import ports, not adapters;
+ *   adapters are injected at the feature composition root; model is
+ *   pure. Bans apply only under `featureRoot` (extraPatterns also
+ *   accepts `model`).
  * @returns {import("eslint").Linter.Config[]} Flat config blocks.
  */
-export function defineLayers({ kitPackage, viewDirs, dataDirs, actionPatterns, extraPatterns = {} }) {
-  for (const [key, value] of Object.entries(extraPatterns)) {
-    if (key !== "kitScope" && key !== "viewData" && key !== "dataUi") {
-      throw new Error(`defineLayers: unknown extraPatterns key "${key}" (want kitScope, viewData or dataUi)`);
-    }
-    if (!Array.isArray(value)) {
-      throw new Error(`defineLayers: extraPatterns.${key} must be a list of no-restricted-imports pattern objects`);
-    }
+export function defineLayers(options) {
+  const { preset, extraPatterns = {} } = options;
+  if (preset === "feature-folders") {
+    return featureFolderLayers(options);
   }
+  if (preset !== undefined) {
+    throw new Error(`defineLayers: unknown preset "${preset}" (want feature-folders)`);
+  }
+  const { kitPackage, viewDirs, dataDirs, actionPatterns } = options;
+  assertExtraPatterns(extraPatterns, ["kitScope", "viewData", "dataUi"]);
   if (!Array.isArray(actionPatterns)) {
     throw new Error("defineLayers: actionPatterns must be a list of import specifiers (may be empty)");
   }
@@ -216,3 +271,128 @@ export function defineLayers({ kitPackage, viewDirs, dataDirs, actionPatterns, e
     },
   ];
 }
+
+const ADAPTER_GROUP = ["**/adapters", "**/adapters/**"];
+const REACT_GROUP = ["react", "react-dom", "react-dom/*", "react/jsx-runtime"];
+
+function featureFolderLayers({
+  kitPackage,
+  featureRoot,
+  extraPatterns = {},
+  viewDirs,
+  dataDirs,
+  actionPatterns,
+}) {
+  if (viewDirs !== undefined || dataDirs !== undefined || actionPatterns !== undefined) {
+    throw new Error("defineLayers: preset feature-folders uses featureRoot, not viewDirs/dataDirs/actionPatterns");
+  }
+  if (typeof featureRoot !== "string" || featureRoot === "") {
+    throw new Error("defineLayers: featureRoot is required for preset feature-folders");
+  }
+  assertExtraPatterns(extraPatterns, ["kitScope", "viewData", "dataUi", "model"]);
+  const root = featureRoot.replace(/\/$/, "");
+  const kitPatterns = [kitPackage, `${kitPackage}/*`];
+  const views = asFiles([`${root}/**/ui/**`]);
+  const adapters = asFiles([`${root}/**/adapters/**`]);
+  const model = asFiles([`${root}/**/model/**`]);
+  const compose = [`${root}/*/index.ts`, `${root}/*/index.tsx`, `${root}/*/compose.ts`, `${root}/*/compose.tsx`];
+  const extras = { kitScope: [], viewData: [], dataUi: [], model: [], ...extraPatterns };
+  return [
+    {
+      name: "zedkit/layers-kit-scope",
+      files: asFiles([root]),
+      ignores: [...views, ...adapters, ...model, ...compose],
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: kitPatterns,
+                message:
+                  "layers-features: UI kit imports are only allowed from view files. Move this import into a view.",
+              },
+              {
+                group: REACT_GROUP,
+                message: "layers-features: only ui/ and the composition root import React.",
+              },
+              {
+                group: ADAPTER_GROUP,
+                message:
+                  "layers-features: inject adapters at the feature composition root (index.ts or compose.ts).",
+              },
+              ...extras.kitScope,
+            ],
+          },
+        ],
+      },
+    },
+    {
+      name: "zedkit/layers-view-data",
+      files: views,
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: ADAPTER_GROUP,
+                message:
+                  "layers-features: UI files import ports, not adapters. Inject the adapter at the feature composition root.",
+              },
+              ...extras.viewData,
+            ],
+          },
+        ],
+      },
+    },
+    {
+      name: "zedkit/layers-data-ui",
+      files: adapters,
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: REACT_GROUP,
+                message: "layers-features: data code is UI-free: no React runtime imports.",
+              },
+              {
+                group: kitPatterns,
+                message: "layers-features: data code is UI-free: no UI kit imports.",
+              },
+              ...extras.dataUi,
+            ],
+          },
+        ],
+      },
+    },
+    {
+      name: "zedkit/layers-model-pure",
+      files: model,
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: REACT_GROUP,
+                message: "layers-features: model is pure: no React runtime. Keep I/O in adapters.",
+              },
+              {
+                group: kitPatterns,
+                message: "layers-features: model is pure: no UI kit imports.",
+              },
+              {
+                group: ADAPTER_GROUP,
+                message: "layers-features: model is pure: adapters are injected at the composition root.",
+              },
+              ...extras.model,
+            ],
+          },
+        ],
+      },
+    },
+  ];
+}