Merge pull request #53 from bartstc/chore/eslint-rule-for-layers

chore: add eslint rule for enforcing layer dependencies

Author: bartstc

docs/architecture.md

@@ -52,14 +52,20 @@ Each feature follows feature slice architecture patterns with four layers:
 
 - **components/** - UI components, presentational and decoupled from business logic (application) and router state. Data access is only through `providers/`.
 - **application/** - Business logic, portable state management (stores, FSMs, form validation), custom hooks. Should not depend on router state or external APIs directly (only through `providers/`).
-- **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, domain errors, and DTOs sourced from `src/lib/api/`. Library-specific code (React Query, etc.) must not leak beyond this layer.
+- **providers/** - Hook composition and data access gateway for the feature slice. Exposes query hooks, mutations, loaders, and domain errors sourced from `src/lib/api/`. When the DTO shape diverges from the domain model, the mapping function lives here — applied inside the query/mutation hook so consumers always receive the correct domain model type.
   - files are named after their primary export or reexport: `useCartProductsQuery` → `use-cart-products-query.ts`, `useAddToCartMutation` → `use-add-to-cart-mutation.ts`
-- **models/** - Domain type definitions, utilities, and type mapping functions.
-  - exposes frontend models for the feature. Components, application, and pages import types from `models/`, never directly from `src/lib/api/`. When the DTO shape is identical, a simple re-export with a domain name suffices (`export type { ProductDto as Product }`). When it diverges, map to a dedicated frontend model.
+- **models/** - Domain type definitions only. Exposes frontend models for the feature. When the DTO shape is identical to the domain model, re-export with a domain name (`export type { ProductDto as Product }`). When it diverges, define the domain type here.
 
-**Dependency rule:** `components/` and `application/` import from `models/` and `providers/`. `providers/` and `models/` have no internal feature dependencies.
+**Dependency rule:**
 
-## API Layer
+| Layer          | May import from                                  |
+| -------------- | ------------------------------------------------ |
+| `components/`  | `application/`, `providers/`, `models/`, `lib/*` |
+| `application/` | `providers/`, `models/`, `lib/*`                 |
+| `providers/`   | `models/`, `lib/api/`, `lib/*`                   |
+| `models/`      | `lib/api/`, `lib/*`                              |
+
+## API Library
 
 `src/lib/api/` is the global home for all HTTP logic: `queryOptions` factories, loaders, mutation hooks, query keys, domain errors, and DTOs, organised by resource. Query files expose `queryOptions` factories (no `useQuery` hooks — hook composition belongs in `providers/`). Feature `providers/` compose hooks on top of those factories and re-export them for feature slice. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
 
@@ -72,8 +78,6 @@ Each feature follows feature slice architecture patterns with four layers:
 | DTO interface | `-dto.ts`        | `cart-product-dto.ts`     |
 | Query keys    | `-query-keys.ts` | `cart-query-keys.ts`      |
 
-Never use `-command.ts`, `-service.ts`, or other suffixes.
-
 ## Key Patterns
 
 | Pattern               | Description                                                      |

eslint.config.mjs

@@ -11,14 +11,77 @@ import reactRefresh from "eslint-plugin-react-refresh";
 import reactYouMightNotNeedAnEffect from "eslint-plugin-react-you-might-not-need-an-effect";
 
 // used by import/no-restricted-paths
+// AIDEV-NOTE: import/no-restricted-paths uses path.relative() for matching — glob wildcards
+// in target/from are NOT supported. All zone lists must be generated per-feature.
 const featureSlices = ["carts", "marketing", "products"];
+const allFeatureSlices = [
+  "auth",
+  "authv2",
+  "carts",
+  "demo",
+  "marketing",
+  "products",
+];
+
 const featureToFeatureZones = featureSlices.map((feature) => ({
   target: `./src/features/${feature}`,
   from: "./src/features",
   except: [`./${feature}`, "./auth"],
   message: "Avoid importing from other features.",
 }));
 
+const featureLayerZones = allFeatureSlices.flatMap((feature) => [
+  // application/ ← components/ (forbidden)
+  {
+    target: `./src/features/${feature}/application`,
+    from: `./src/features/${feature}/components`,
+    message: "application/ must not depend on components/.",
+  },
+  // providers/ ← application/ or components/ (forbidden)
+  {
+    target: `./src/features/${feature}/providers`,
+    from: `./src/features/${feature}/application`,
+    message: "providers/ must not depend on application/.",
+  },
+  {
+    target: `./src/features/${feature}/providers`,
+    from: `./src/features/${feature}/components`,
+    message: "providers/ must not depend on components/.",
+  },
+  // models/ ← any feature layer (forbidden)
+  {
+    target: `./src/features/${feature}/models`,
+    from: `./src/features/${feature}/application`,
+    message: "models/ must not depend on application/.",
+  },
+  {
+    target: `./src/features/${feature}/models`,
+    from: `./src/features/${feature}/components`,
+    message: "models/ must not depend on components/.",
+  },
+  {
+    target: `./src/features/${feature}/models`,
+    from: `./src/features/${feature}/providers`,
+    message: "models/ must not depend on providers/.",
+  },
+]);
+
+// Prevents lib/api/ from leaking beyond providers/ and models/.
+const apiLayerIsolationZones = allFeatureSlices.flatMap((feature) => [
+  {
+    target: `./src/features/${feature}/components`,
+    from: "./src/lib/api",
+    message:
+      "src/lib/api/ must not be imported in components/. Use providers/ for data queries and mutations and models/ for types.",
+  },
+  {
+    target: `./src/features/${feature}/application`,
+    from: "./src/lib/api",
+    message:
+      "src/lib/api/ must not be imported in application/. Use providers/ for data queries and mutations and models/ for types.",
+  },
+]);
+
 export default defineConfig(
   {
     ignores: [
@@ -197,7 +260,29 @@ export default defineConfig(
       "import/no-restricted-paths": [
         "error",
         {
-          zones: featureToFeatureZones,
+          zones: [
+            ...featureToFeatureZones,
+            ...featureLayerZones,
+            ...apiLayerIsolationZones,
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: ["./src/pages/**"],
+    rules: {
+      "import/no-restricted-paths": [
+        "error",
+        {
+          zones: [
+            {
+              target: "./src/pages",
+              from: "./src/lib/api",
+              message:
+                "src/lib/api/ must not be imported in pages/. Use features/*/providers/ for data and features/*/models/ for types.",
+            },
+          ],
         },
       ],
     },

src/features/carts/application/use-add-to-cart.ts

@@ -1,5 +1,5 @@
 import { useAuthStore } from "@/features/auth/application/auth-store";
-import { useProductAddedDialogStore } from "@/features/carts/components/AddToCartButton/use-product-added-dialog-store";
+import { useProductAddedDialogStore } from "@/features/carts/application/use-product-added-dialog-store";
 import {
   useAddToCartMutation,
   UnknownProductError,

…Button/use-product-added-dialog-store.ts …cation/use-product-added-dialog-store.tssrc/features/carts/components/AddToCartButton/use-product-added-dialog-store.ts renamed to src/features/carts/application/use-product-added-dialog-store.ts src/features/carts/components/AddToCartButton/use-product-added-dialog-store.ts renamed to src/features/carts/application/use-product-added-dialog-store.ts

@@ -7,7 +7,7 @@ import {
   Text,
 } from "@chakra-ui/react";
 
-import { useProductAddedDialogStore } from "@/features/carts/components/AddToCartButton/use-product-added-dialog-store";
+import { useProductAddedDialogStore } from "@/features/carts/application/use-product-added-dialog-store";
 import { useTranslations } from "@/lib/i18n/use-transations";
 import { useNavigate } from "@/lib/router";
 import { routes } from "@/lib/router/routes";