@zedtech/zedkit-quality 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zedtech-fr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @zedtech/zedkit-quality
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@zedtech/zedkit-quality.svg)](https://www.npmjs.com/package/@zedtech/zedkit-quality)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/zedtech-fr/zedkit/blob/main/LICENSE)
+
+Shared quality setup: UI lint preset, route/view/data layer boundaries,
+and one strict TypeScript base. Consume it from any repo — do not copy
+it. Original work by the same author.
+
+## Install
+
+```sh
+pnpm add -D @zedtech/zedkit-quality
+```
+
+Peer dependencies (`eslint`, `eslint-plugin-jsx-a11y`,
+`eslint-plugin-better-tailwindcss`) install alongside it.
+
+## Usage
+
+```js
+// eslint.config.mjs
+import { defineLayers, uiPreset } from "@zedtech/zedkit-quality";
+
+export default [
+  ...uiPreset({ entryPoint: "./app/globals.css" }),
+  ...defineLayers({
+    kitPackage: "@acme/ui",
+    viewDirs: ["app/**/ui/**"],
+    dataDirs: ["lib/**"],
+    actionPatterns: ["@/lib/*", "**/actions", "**/actions/**"],
+  }),
+];
+```
+
+```jsonc
+// tsconfig.json
+{
+  "extends": "@zedtech/zedkit-quality/tsconfig",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}
+```
+
+## When to use
+
+Reach for this package when several repos must enforce the same gates:
+UI lint rules, layer boundaries, one strict `tsconfig` base. One import
+per need, versioned updates everywhere. For AI agent setup (skills,
+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.
+- `defineLayers({ kitPackage, viewDirs, dataDirs, actionPatterns })` —
+  `no-restricted-imports` blocks for routes -> views -> data: the UI kit
+  is only imported from views, views never import data clients or
+  actions, data files import no UI.
+- `@zedtech/zedkit-quality/tsconfig` — the strict base (`strict`,
+  `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`,
+  `noUnusedLocals`, and more). Extend it, do not copy it.
+
+Find helpers by need in [CATALOG.md](CATALOG.md).
+
+## Install or copy?
+
+Install it: these configs must stay identical across repos, and a copy
+drifts silently. Versioned updates propagate through normal bump PRs.
+
+## Verify
+
+```sh
+pnpm --filter @zedtech/zedkit-quality typecheck && pnpm --filter @zedtech/zedkit-quality lint && pnpm --filter @zedtech/zedkit-quality test
+```

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@zedtech/zedkit-quality",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Shared quality setup: UI lint preset, route/view/data layer boundaries, and one strict TypeScript base — consume, do not copy.",
+  "keywords": [
+    "eslint",
+    "eslint-config",
+    "tsconfig",
+    "typescript",
+    "strict",
+    "layers",
+    "architecture",
+    "a11y",
+    "tailwindcss",
+    "code-quality"
+  ],
+  "homepage": "https://github.com/zedtech-fr/zedkit/tree/main/packages/quality",
+  "bugs": {
+    "url": "https://github.com/zedtech-fr/zedkit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zedtech-fr/zedkit",
+    "directory": "packages/quality"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "import": "./src/index.mjs"
+    },
+    "./eslint": {
+      "types": "./src/eslint.d.mts",
+      "import": "./src/eslint.mjs"
+    },
+    "./tsconfig": "./tsconfig.base.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/index.mjs",
+    "src/index.d.mts",
+    "src/eslint.mjs",
+    "src/eslint.d.mts",
+    "tsconfig.base.json"
+  ],
+  "zedkit": {
+    "noBuild": true
+  },
+  "peerDependencies": {
+    "eslint": "9.39.5",
+    "eslint-plugin-better-tailwindcss": "4.10.0",
+    "eslint-plugin-jsx-a11y": "6.10.2"
+  },
+  "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"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src tests"
+  }
 }

package/src/eslint.d.mts

@@ -0,0 +1,21 @@
+import type { Linter } from "eslint";
+
+export interface UiPresetOptions {
+  /** Path to the repo's Tailwind CSS entry. Required, no default. */
+  readonly entryPoint: string;
+}
+
+export function uiPreset(options: UiPresetOptions): Linter.Config[];
+
+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. */
+  readonly actionPatterns: readonly string[];
+}
+
+export function defineLayers(options: DefineLayersOptions): Linter.Config[];

package/src/eslint.mjs

@@ -0,0 +1,188 @@
+// Shareable UI lint preset: enforces docs/frontend-charter.md by tools.
+//
+// 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)
+//
+// 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";
+
+const PALETTE =
+  "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|fuchsia|pink|rose";
+const COLOR_UTILS =
+  "bg|text|border|ring|ring-offset|divide|from|via|to|decoration|outline|accent|caret|fill|stroke|shadow|placeholder";
+
+/**
+ * UI lint preset for .tsx/.jsx files.
+ *
+ * @param {{ entryPoint: string }} options - Path to the repo's Tailwind CSS
+ * entry, so the plugin knows the theme tokens. Required, no default: the
+ * per-repo CSS path is the one thing that varies.
+ * @returns {import("eslint").Linter.Config[]} Flat config blocks.
+ */
+export function uiPreset({ entryPoint }) {
+  if (typeof entryPoint !== "string" || entryPoint === "") {
+    throw new Error("uiPreset: `entryPoint` is required (path to your Tailwind CSS entry).");
+  }
+  return [
+    {
+      name: "zedkit/ui-a11y",
+      files: ["**/*.tsx", "**/*.jsx"],
+      ...jsxA11y.flatConfigs.recommended,
+    },
+    {
+      name: "zedkit/ui-tailwind",
+      files: ["**/*.tsx", "**/*.jsx"],
+      plugins: { "better-tailwindcss": betterTailwindcss },
+      settings: {
+        "better-tailwindcss": {
+          entryPoint,
+        },
+      },
+      rules: {
+        "better-tailwindcss/enforce-consistent-class-order": "error",
+        "better-tailwindcss/no-duplicate-classes": "error",
+        "better-tailwindcss/no-conflicting-classes": "error",
+        "better-tailwindcss/no-unknown-classes": "error",
+        "better-tailwindcss/no-restricted-classes": [
+          "error",
+          {
+            restrict: [
+              {
+                pattern: `(^|:)(${COLOR_UTILS})-(${PALETTE}|white|black)(-|/|$)`,
+                message:
+                  "Raw palette colors are banned. Use a semantic theme token (see docs/frontend-charter.md).",
+              },
+              {
+                pattern: "\\[(#|rgb|hsl)",
+                message:
+                  "Arbitrary color values are banned. Use a semantic theme token (see docs/frontend-charter.md).",
+              },
+              {
+                pattern: "text-\\[[^\\]]*px",
+                message: "Raw px font sizes are banned. Use the type scale (see docs/frontend-charter.md).",
+              },
+            ],
+          },
+        ],
+        // 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.
+        "no-restricted-syntax": [
+          "error",
+          {
+            selector: "TryStatement",
+            message: "Raw try/catch is banned. Use tryCatch/tryCatchAsync from @zedtech/zedkit-core.",
+          },
+          {
+            selector: 'JSXAttribute[name.name="style"]',
+            message: "Inline style attributes are banned. Use theme tokens (see docs/frontend-charter.md).",
+          },
+        ],
+      },
+    },
+  ];
+}
+
+// JS files the kit-scope block applies to (minus the view/data ignores).
+const JS_FILES = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
+const JS_BRACE = "{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
+
+// Flat-config `files` never matches a bare directory (`app/ui/**` matches
+// nothing): dir-style entries become `dir/**/*.{exts}`. Entries that
+// already name files (`**/*.tsx`, braces) pass through untouched. A leaf
+// containing a dot counts as a file pattern, so a directory whose own
+// name has a dot must use a trailing `/**` to be treated as a folder.
+function asFiles(patterns) {
+  return patterns.map((entry) => {
+    const leaf = entry.slice(entry.lastIndexOf("/") + 1);
+    if (entry.endsWith("}") || leaf.includes(".")) return entry;
+    const stripped = entry.endsWith("/**") ? entry.slice(0, -3) : entry;
+    const dir = stripped.endsWith("/") ? stripped.slice(0, -1) : stripped;
+    return `${dir}/**/*.${JS_BRACE}`;
+  });
+}
+
+/**
+ * Route/view/data layer boundaries as `no-restricted-imports` blocks.
+ * Dependencies run one way (routes -> views -> data):
+ * - the UI kit is only imported from view files;
+ * - 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[] }} 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.
+ * @returns {import("eslint").Linter.Config[]} Flat config blocks.
+ */
+export function defineLayers({ kitPackage, viewDirs, dataDirs, actionPatterns }) {
+  const kitPatterns = [kitPackage, `${kitPackage}/*`];
+  const views = asFiles(viewDirs);
+  const data = asFiles(dataDirs);
+  return [
+    {
+      name: "zedkit/layers-kit-scope",
+      files: JS_FILES,
+      ignores: [...views, ...data],
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: kitPatterns,
+                message: "UI kit imports are only allowed from view files. Move this import into a view.",
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      name: "zedkit/layers-view-data",
+      files: views,
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: [...actionPatterns],
+                message: "Views receive data as props and never import data clients or server actions.",
+              },
+            ],
+          },
+        ],
+      },
+    },
+    {
+      name: "zedkit/layers-data-ui",
+      files: data,
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: ["react", "react-dom", "react-dom/*", "react/jsx-runtime"],
+                message: "Data code is UI-free: no React runtime imports.",
+              },
+              {
+                group: kitPatterns,
+                message: "Data code is UI-free: no UI kit imports.",
+              },
+            ],
+          },
+        ],
+      },
+    },
+  ];
+}

package/src/index.d.mts

@@ -0,0 +1,2 @@
+export { defineLayers, uiPreset } from "./eslint.mjs";
+export type { DefineLayersOptions, UiPresetOptions } from "./eslint.mjs";

package/src/index.mjs

@@ -0,0 +1 @@
+export { defineLayers, uiPreset } from "./eslint.mjs";

package/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  }
+}