@stapel/eslint-plugin 0.2.0 → 0.4.0

package/README.md

@@ -31,11 +31,41 @@ The `recommended` preset:
 - turns the rules on for `**/*.{ts,tsx,js,jsx,mjs,…}` (JSX-only rules on `*.{tsx,jsx}`);
 - **overrides** `no-raw-token-import` **off** in theme-config / showcase / demo / scripts,
   `no-raw-fetch` and `no-string-paths` **off** in the codegen api layer
-  (`**/api/**`, `*client.ts`, `generated/`), and `query-keys-from-factory`
-  **off** in the key-factory file (`**/queryKeys.*`);
+  (`**/api/**`, `*client.ts`, `generated/`), `query-keys-from-factory`
+  **off** in the key-factory file (`**/queryKeys.*`), `no-raw-storage` **off**
+  in core's storage/repository internals, and `no-adhoc-401` **off** in core's
+  client/session (each rule's one legal home);
 - **overrides** the content rules off in tests and fixtures (they exercise the
   anti-patterns on purpose).
 
+### `reserved-paths.json`
+
+`stapel/no-reserved-backend-route` reads a project-root `reserved-paths.json`
+(no fixed location config beyond `settings.stapel.reservedPathsFile` — see
+below), the same flat projection stapel-tools' project generator emits:
+
+```json
+{
+  "reservedPathPrefixes": [
+    "/admin",
+    "/staticfiles",
+    "/media",
+    "/calendar/api",
+    "/calendar/swagger"
+  ]
+}
+```
+
+`reservedPathPrefixes` is a flat array of path prefixes the backend owns. A
+route is flagged when it **equals** a prefix or continues **past a segment
+boundary** beneath one (`/calendar/api/x` matches `/calendar/api`;
+`/calendar-archive` does not). **Never** put a bare module root
+(`/calendar`) in this list — the generator only emits sub-path reservations,
+because a bare root belongs to the frontend SPA by convention. If the file is
+missing, the rule is a no-op — it never fails the lint run.
+
+
+
 ## Rules
 
 | Rule | Catches |
@@ -54,6 +84,9 @@ The `recommended` preset:
 | `stapel/known-event` (warn) | `track()`/`tracked()` with an event name absent from the generated `events.json` — registry drift; run `pnpm gen:events` (§3) |
 | `stapel/no-direct-analytics-provider` | importing an analytics vendor SDK (posthog-js, mixpanel, `@amplitude/*`, `@segment/*`, …) outside the core facade's provider adapters (`analytics/providers.*`) — bypasses consent/PII/queue (§3). Extend the vendor list via `options.providers` or `settings.stapel.providerModules` |
 | `stapel/demo-literal-meta` | `defineDemo()` with non-literal meta (dynamic `id`/`title`/`description`/`covers`) — breaks static extraction into `demos.json`/`manifest.demos` (§4.2) |
+| `stapel/no-raw-storage` | direct `localStorage`/`sessionStorage`/`indexedDB` (bare or via `window.`/`globalThis.`/`self.`) or importing `idb-keyval` outside `@stapel/core`'s repository layer — raw storage is neither wiped on logout nor encrypted; persist through `createRepository()` (frontend-core-architecture-v2 §43.4). Off in core's `storage.ts`/`repository.ts`/`query.ts` (the one legal home) and in tests. Extend the banned module list via `options.modules` or `settings.stapel.storageModules` |
+| `stapel/no-adhoc-401` | comparing a status to the literal `401` (`===`/`!==`/`case 401:`) or wiring an axios-style `*.interceptors` chain — ad hoc 401 handling bypasses the single-flight refresh + logout-hook registry; 401s are handled ONCE, in core's `createStapelClient` (`onAuthRefresh` seam) + `SessionManager` (§43.2). Off in core's `client.ts`/`session.ts` and in tests |
+| `stapel/no-reserved-backend-route` | an SPA route (`<Route path="…">`, a `createBrowserRouter`/`createHashRouter`/`createMemoryRouter` array literal, or any `{ path: "…", element/Component/children/index/errorElement/loader/action/lazy: … }` RouteObject) whose path falls INTO a reserved backend sub-path — `/<mod>/api/…`, `/<mod>/swagger…`, or the project-wide `/admin`, `/staticfiles`, `/media` (§57 nginx canon). A **bare module root** (`/calendar`) is legitimate and never flagged — roots belong to the frontend; only sub-paths collide. Data-driven: reads the flat `reservedPathPrefixes` array from `reserved-paths.json` (emitted by stapel-tools' project generator) at the workspace root, or `settings.stapel.reservedPathsFile`/`reservedPaths`. No catalog → no-op (never a crash) |
 
 ### Settings
 
@@ -66,8 +99,10 @@ settings: {
     i18nKeys: ["auth.otp.…"],   // or i18nManifests: [manifest, …]
     httpModules: ["my-http"],   // extra banned HTTP clients
     rawModules: ["@x/raw"],     // extra raw-token entry points
+    storageModules: ["level"],  // extra banned storage-backend packages
     eventsManifests: [manifest],// or eventNames: ["pricing.plan.selected", …]
-    operationsManifests: [manifest], // or operationPaths: ["/auth/api/me/", …]
+    operationsManifests: [manifest], // or operationPaths: ["/auth/api/v1/me/", …]
+    reservedPathsFile: "./reserved-paths.json", // or reservedPaths: ["/admin", …]
     httpVerbs: ["get","post"],   // client methods no-string-paths inspects
     queryHooks: ["useQuery"],    // extra react-query hooks to inspect for keys
     trackedWrappers: ["tracked"],

package/index.js

@@ -18,6 +18,9 @@ import eventLiteralMeta from "./rules/event-literal-meta.js";
 import knownEvent from "./rules/known-event.js";
 import noDirectAnalyticsProvider from "./rules/no-direct-analytics-provider.js";
 import demoLiteralMeta from "./rules/demo-literal-meta.js";
+import noRawStorage from "./rules/no-raw-storage.js";
+import noAdhoc401 from "./rules/no-adhoc-401.js";
+import noReservedBackendRoute from "./rules/no-reserved-backend-route.js";
 
 const rules = {
   "no-raw-colors": noRawColors,
@@ -37,6 +40,12 @@ const rules = {
   "no-direct-analytics-provider": noDirectAnalyticsProvider,
   // Showcase guardrail (frontend-guardrails §4, task G7).
   "demo-literal-meta": demoLiteralMeta,
+  // Session-substrate guardrails (frontend-core-architecture-v2 §43).
+  "no-raw-storage": noRawStorage,
+  "no-adhoc-401": noAdhoc401,
+  // Front/back path-collision guardrail (owner directive: SPA router must not
+  // claim a reserved backend sub-path).
+  "no-reserved-backend-route": noReservedBackendRoute,
 };
 
 const plugin = {
@@ -81,6 +90,7 @@ const FETCH_ALLOWED = [
   "**/api/**",
   "**/*client.{ts,js}",
   "**/analytics/providers.{ts,js}",
+  "**/analytics/src/providers.{ts,js}",
   "**/scripts/**",
 ];
 
@@ -101,6 +111,23 @@ const KEY_FACTORY = [
   "**/query-keys.{ts,tsx,js,mjs}",
 ];
 
+// @stapel/core's storage/repository internals — the ONE legal home of direct
+// localStorage/indexedDB access (§43.4 override; everything else persists
+// through createRepository, which is what makes wipe-at-logout mechanical).
+const STORAGE_ALLOWED = [
+  "**/core/src/storage.{ts,js}",
+  "**/core/src/repository.{ts,js}",
+  "**/core/src/query.{ts,js}",
+];
+
+// @stapel/core's client + session internals — the ONE legal home of 401
+// handling (§43.2 override; the onAuthRefresh seam + SessionManager.refresh()
+// are where the single-flight retry lives).
+const ADHOC_401_ALLOWED = [
+  "**/core/src/client.{ts,js}",
+  "**/core/src/session.{ts,js}",
+];
+
 /**
  * Flat-config `recommended` preset. Consumers spread it AFTER their parser
  * config:
@@ -132,6 +159,15 @@ const recommended = [
       "stapel/no-direct-analytics-provider": "error",
       // Showcase (§4): defineDemo meta must stay literal (extractable).
       "stapel/demo-literal-meta": "error",
+      // Session substrate (frontend-core-architecture-v2 §43): persistence
+      // only through createRepository; 401 handling only in core's client
+      // + SessionManager.
+      "stapel/no-raw-storage": "error",
+      "stapel/no-adhoc-401": "error",
+      // Path-collision guardrail: the SPA router must not claim a reserved
+      // backend sub-path (/<mod>/api/…, /<mod>/swagger…, /admin, /staticfiles,
+      // /media — §57 nginx canon). No-op without reserved-paths.json.
+      "stapel/no-reserved-backend-route": "error",
     },
   },
   {
@@ -158,10 +194,22 @@ const recommended = [
     files: KEY_FACTORY,
     rules: { "stapel/query-keys-from-factory": "off" },
   },
+  {
+    // Core's storage/repository internals — the one legal home of raw
+    // storage access (§43.4 override).
+    files: STORAGE_ALLOWED,
+    rules: { "stapel/no-raw-storage": "off" },
+  },
+  {
+    // Core's client + session — the one legal home of 401 handling
+    // (§43.2 override).
+    files: ADHOC_401_ALLOWED,
+    rules: { "stapel/no-adhoc-401": "off" },
+  },
   {
     // The facade's provider adapters — the ONE legal home of vendor SDK
     // imports (§2.2 override; mirrors the FETCH_ALLOWED api-layer carve-out).
-    files: ["**/analytics/providers.{ts,js}", "**/analytics/providers/**"],
+    files: ["**/analytics/providers.{ts,js}", "**/analytics/src/providers.{ts,js}", "**/analytics/providers/**"],
     rules: { "stapel/no-direct-analytics-provider": "off" },
   },
   {
@@ -183,6 +231,13 @@ const recommended = [
       "stapel/known-event": "off",
       "stapel/no-direct-analytics-provider": "off",
       "stapel/demo-literal-meta": "off",
+      // Tests legitimately assert on raw storage state (the wipe-at-logout
+      // contract test greps localStorage directly) and on 401 fixtures.
+      "stapel/no-raw-storage": "off",
+      "stapel/no-adhoc-401": "off",
+      // Route fixtures legitimately probe reserved-path collisions on purpose
+      // (that's what this rule's own tests do).
+      "stapel/no-reserved-backend-route": "off",
       // require-disable-description stays ON — disable hygiene applies everywhere.
     },
   },

package/lib/data.js

@@ -333,6 +333,78 @@ export function loadOperationCatalog(settings = {}) {
   return _operationCatalogDefault;
 }
 
+// ── reserved backend-path catalog (reserved-paths.json) ──────────────────────
+//
+// no-reserved-backend-route reads the SAME projection stapel-tools' project
+// generator emits at the workspace root: a flat array of path PREFIXES a
+// backend module reserves under its own slug (`/<mod>/api/…`,
+// `/<mod>/swagger…`), plus the project-wide infra prefixes nginx enforces
+// (`/admin`, `/staticfiles`, `/media` — §57 canon, compose_templates.NGINX_CONF).
+// Schema: `{ "reservedPathPrefixes": string[] }`. A bare module ROOT
+// (`/<mod>`) must never appear in the list — roots belong to the frontend SPA
+// by convention; only sub-path reservations are catalogued. A missing/
+// unreadable file degrades the rule to a no-op (empty catalog, never a
+// crash) — exactly like the token/i18n/events/operation loaders above (§2.1).
+
+function discoverReservedPathsFile(from) {
+  const root = workspaceRoot(from);
+  if (root) {
+    const p = join(root, "reserved-paths.json");
+    if (existsSync(p)) return p;
+  }
+  const local = join(from, "reserved-paths.json");
+  if (existsSync(local)) return local;
+  return null;
+}
+
+function buildReservedPathCatalog(prefixes) {
+  const list = (prefixes ?? []).filter(
+    (p) => typeof p === "string" && p.length > 0
+  );
+  return {
+    prefixes: list,
+    loaded: list.length > 0,
+    /**
+     * The reserved prefix a route path falls INTO — equal to it, or past a
+     * segment boundary beneath it — else null. A route that merely shares a
+     * prefix's leading segment (a bare module root, e.g. "/calendar" against
+     * reserved "/calendar/api") does NOT match: roots are the frontend's by
+     * canon, only sub-paths are reserved.
+     */
+    matches: (route) => {
+      if (typeof route !== "string" || !route.startsWith("/")) return null;
+      for (const p of list) {
+        const boundary = p.endsWith("/") ? p : `${p}/`;
+        if (route === p || route.startsWith(boundary)) return p;
+      }
+      return null;
+    },
+  };
+}
+
+let _reservedPathCatalogDefault;
+export function loadReservedPathCatalog(settings = {}) {
+  if (settings.reservedPaths) {
+    return buildReservedPathCatalog(settings.reservedPaths);
+  }
+  if (settings.reservedPathsFile) {
+    // Explicit override → never memoized (mirrors the other loaders: only the
+    // zero-config discovered default is cached).
+    return buildReservedPathCatalog(
+      readJson(settings.reservedPathsFile)?.reservedPathPrefixes
+    );
+  }
+  if (!_reservedPathCatalogDefault) {
+    const file = discoverReservedPathsFile(
+      process.cwd ? process.cwd() : HERE
+    );
+    _reservedPathCatalogDefault = buildReservedPathCatalog(
+      file ? readJson(file)?.reservedPathPrefixes : undefined
+    );
+  }
+  return _reservedPathCatalogDefault;
+}
+
 /** Read `context.settings.stapel` (flat config) with a stable empty default. */
 export function stapelSettings(context) {
   return (context.settings && context.settings.stapel) || {};
@@ -344,6 +416,7 @@ export function __resetCaches() {
   _i18nDefault = undefined;
   _eventsCatalogDefault = undefined;
   _operationCatalogDefault = undefined;
+  _reservedPathCatalogDefault = undefined;
 }
 
 export { resolve as _resolve };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/eslint-plugin",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Stapel frontend guardrails as static lint rules (frontend-guardrails §2): no raw colours, no raw fetch, no raw-ramp imports, i18n-key existence, no hardcoded user-facing text — every rule reads the same generated artifacts (tokens manifest, i18n key registries) as the codegen, so lint and code never drift. Ships a flat-config `recommended` preset plus a self-contained stylelint preset for CSS.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@stapel/tokens": "^0.2.0"
+    "@stapel/tokens": "^0.4.0"
   },
   "peerDependencies": {
     "eslint": ">=9",

package/rules/no-adhoc-401.js

@@ -0,0 +1,68 @@
+// stapel/no-adhoc-401 — frontend-core-architecture-v2 §43.2.
+// 401 handling (single-flight refresh → retry once → SessionManager.sessionLost())
+// lives in ONE place: `@stapel/core`'s `createStapelClient` (`onAuthRefresh`
+// seam) + `SessionManager`. A module/service writing its own "if status is
+// 401, refresh/redirect/retry" branch bypasses the single-flight coalescing
+// and the logout-hook registry silently — the failure mode is invisible until
+// two concurrent requests both refresh and race each other. The recommended
+// preset turns this rule OFF for `@stapel/core`'s own client/session
+// internals (the ONE legal home), mirroring the no-raw-fetch api-layer
+// carve-out.
+
+// Named constant (not an inline literal in the comparison below) so the rule
+// passes ITSELF — its own `value === HTTP_UNAUTHORIZED` check must not read
+// as ad hoc 401 handling when the monorepo lints this file.
+const HTTP_UNAUTHORIZED = 401;
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow ad hoc 401 handling / auth interceptors outside @stapel/core's client and SessionManager.",
+    },
+    schema: [],
+    messages: {
+      literal401:
+        "Ad hoc 401 handling. 401s are handled ONCE, in @stapel/core's createStapelClient (onAuthRefresh seam) + SessionManager.refresh() — single-flight refresh, retry once, SessionManager.sessionLost() on failure (frontend-core-architecture-v2 §43.2). Wire onAuthRefresh to your SessionManager instead of branching on the status code here.",
+      interceptor:
+        "Ad hoc auth interceptor ({{what}}). Requests already go through createStapelClient, whose onAuthRefresh/onVerificationChallenge seams are the one legal place to intercept auth failures — see §43.2.",
+    },
+  },
+  create(context) {
+    function isNumeric401(node) {
+      return node.type === "Literal" && node.value === HTTP_UNAUTHORIZED;
+    }
+
+    return {
+      BinaryExpression(node) {
+        if (!["==", "===", "!=", "!=="].includes(node.operator)) return;
+        if (isNumeric401(node.left) || isNumeric401(node.right)) {
+          context.report({ node, messageId: "literal401" });
+        }
+      },
+
+      SwitchCase(node) {
+        if (node.test && isNumeric401(node.test)) {
+          context.report({ node, messageId: "literal401" });
+        }
+      },
+
+      // `client.interceptors.response.use(...)` / `axios.interceptors...` —
+      // axios-shaped ad hoc auth interceptors, regardless of the object.
+      MemberExpression(node) {
+        if (
+          !node.computed &&
+          node.property.type === "Identifier" &&
+          node.property.name === "interceptors"
+        ) {
+          context.report({
+            node,
+            messageId: "interceptor",
+            data: { what: "*.interceptors" },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-direct-analytics-provider.js

@@ -1,5 +1,6 @@
 // stapel/no-direct-analytics-provider — frontend-guardrails §2.2 / §3.
-// Analytics goes through the @stapel/core facade (consent gate, PII guard,
+// Analytics goes through the Stapel facade (the @stapel/core type seam,
+// implemented by @stapel/analytics): consent gate, PII guard,
 // offline queue, fan-out), NEVER straight into a vendor SDK. Importing a
 // provider package anywhere but the facade's provider-adapter module bypasses
 // consent and PII enforcement in one line — the cheapest F9 violation there
@@ -49,7 +50,7 @@ export default {
     ],
     messages: {
       directProvider:
-        'Direct analytics provider import "{{source}}". Emit through the @stapel/core facade instead — analytics.track(event, props) / tracked(event, props, handler) — which owns consent, PII guarding, and the offline queue (§3). Provider SDKs are wired ONCE, in the facade\'s provider adapter (analytics/providers.ts). See @stapel/core/llms.txt §analytics.',
+        'Direct analytics provider import "{{source}}". Emit through the Stapel analytics facade instead — analytics.track(event, props) / tracked(event, props, handler) — which owns consent, PII guarding, and the offline queue (§3). Provider SDKs are wired ONCE, in the facade\'s provider adapter (analytics/providers.ts — implementation: @stapel/analytics; type seam: @stapel/core).',
     },
   },
   create(context) {

package/rules/no-raw-storage.js

@@ -0,0 +1,126 @@
+// stapel/no-raw-storage — frontend-core-architecture-v2 §43.4.
+// `createRepository` (@stapel/core) is the ONE sanctioned client-side
+// persistence primitive: `scope: "user"` repositories auto-wipe on logout
+// (no opt-out) and are encrypted by default — a guarantee that only holds if
+// nothing else in the app reaches `localStorage`/`sessionStorage`/`indexedDB`
+// directly, since that data would never be torn down or encrypted. Direct
+// access is banned everywhere except `@stapel/core`'s own storage/repository
+// internals (the recommended preset turns this rule OFF there via a file
+// override, mirroring the no-raw-fetch api-layer carve-out).
+import { stapelSettings } from "../lib/data.js";
+
+const STORAGE_GLOBALS = new Set(["localStorage", "sessionStorage"]);
+const IDB_GLOBALS = new Set(["indexedDB"]);
+const GLOBAL_HOSTS = new Set(["window", "self", "globalThis"]);
+const BANNED_IMPORTS = new Set(["idb-keyval"]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow direct localStorage/sessionStorage/indexedDB access outside @stapel/core's repository layer.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          modules: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      rawStorage:
+        'Direct {{what}} access. Persist through createRepository(namespace, { scope, storage, encrypted }) (@stapel/core) instead — it is the one sanctioned client-side store: scope "user" auto-wipes on logout (no opt-out) and is encrypted by default, scope "app" survives logout. Raw storage is neither wiped nor encrypted (frontend-core-architecture-v2 §43.4).',
+      rawImport:
+        'Import of storage-backend package "{{source}}". Use createRepository() (@stapel/core) instead of building on this directly — see §43.4.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const extraModules = context.options[0]?.modules ?? [];
+    const bannedModules = new Set([
+      ...BANNED_IMPORTS,
+      ...(settings.storageModules ?? []),
+      ...extraModules,
+    ]);
+
+    function report(node, what) {
+      context.report({ node, messageId: "rawStorage", data: { what } });
+    }
+
+    function identifierName(node) {
+      return node.type === "Identifier" ? node.name : null;
+    }
+
+    function isStorageName(name) {
+      return STORAGE_GLOBALS.has(name) || IDB_GLOBALS.has(name);
+    }
+
+    return {
+      // Bare `localStorage` / `sessionStorage` / `indexedDB` uses — resolved
+      // through scope analysis so a local binding that merely SHARES the name
+      // (`function f(indexedDB) {…}`) is never flagged: only references that
+      // resolve to a global (env/globals config) or to nothing at all (the
+      // usual appearance of browser globals) are the real storage globals.
+      "Program:exit"(node) {
+        const globalScope = context.sourceCode.getScope(node);
+        // Unresolved references — no declaration anywhere in the file.
+        for (const ref of globalScope.through) {
+          const name = ref.identifier.name;
+          if (isStorageName(name)) report(ref.identifier, name);
+        }
+        // References that RESOLVE to a declared ambient global (a variable
+        // with no defs, injected via languageOptions.globals).
+        for (const name of [...STORAGE_GLOBALS, ...IDB_GLOBALS]) {
+          const variable = globalScope.set.get(name);
+          if (!variable || variable.defs.length > 0) continue;
+          for (const ref of variable.references) {
+            report(ref.identifier, name);
+          }
+        }
+      },
+
+      // `window.localStorage`, `self.indexedDB`, `globalThis.sessionStorage`.
+      MemberExpression(node) {
+        if (node.computed) return;
+        const objectName = identifierName(node.object);
+        const propertyName = identifierName(node.property);
+        if (
+          objectName &&
+          GLOBAL_HOSTS.has(objectName) &&
+          propertyName &&
+          (STORAGE_GLOBALS.has(propertyName) || IDB_GLOBALS.has(propertyName))
+        ) {
+          report(node, `${objectName}.${propertyName}`);
+        }
+      },
+
+      ImportDeclaration(node) {
+        if (bannedModules.has(node.source.value)) {
+          context.report({
+            node,
+            messageId: "rawImport",
+            data: { source: node.source.value },
+          });
+        }
+      },
+
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "require" &&
+          node.arguments[0]?.type === "Literal" &&
+          bannedModules.has(node.arguments[0].value)
+        ) {
+          context.report({
+            node,
+            messageId: "rawImport",
+            data: { source: node.arguments[0].value },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-reserved-backend-route.js

@@ -0,0 +1,216 @@
+// stapel/no-reserved-backend-route — path-collision guardrail between the SPA
+// router and the backend's reserved namespace (§57 nginx canon:
+// stapel-tools' _compose_templates.NGINX_CONF / NGINX_LOCAL_CONF_TEMPLATE —
+// "a frontend app must never define a client route starting with
+// /staticfiles/, /media/ or /<backend-slug>/api|swagger…").
+//
+// Canon (owner directive): a BARE module root (`/calendar`) is legitimate —
+// roots belong to the frontend. Only a route that falls INTO a reserved
+// SUB-path (`/calendar/api/…`, `/calendar/swagger…`, and the project-wide
+// `/admin`, `/staticfiles`, `/media`) collides with the backend. The reserved
+// list itself is data-driven — read from `reserved-paths.json` (the same
+// projection stapel-tools' generator emits), never hand-maintained here, so
+// the rule tracks a project's actual module set (§2.1). A missing catalog
+// degrades the rule to a no-op (never a crash) — same policy as every other
+// data-driven rule in this plugin.
+//
+// Two detector shapes, in the spirit of the other route/path guardrails
+// (no-string-paths):
+//   1. JSX — <Route path="…"> (react-router).
+//   2. Object route configs — a `path` property on an object that reads as a
+//      RouteObject (has an `element`/`Component`/`children`/`index`/
+//      `errorElement`/`loader`/`action`/`lazy` sibling), OR sits inside the
+//      array literal passed straight to `createBrowserRouter`/
+//      `createHashRouter`/`createMemoryRouter` — covers `useRoutes([...])`
+//      configs and router-factory calls alike.
+// Only string literals and the static prefix of a template literal are
+// checked (dynamic segments are unknowable — false-positive policy, same as
+// no-string-paths).
+import { loadReservedPathCatalog, stapelSettings } from "../lib/data.js";
+
+const ROUTER_FACTORIES = new Set([
+  "createBrowserRouter",
+  "createHashRouter",
+  "createMemoryRouter",
+  "createStaticRouter",
+]);
+
+const ROUTE_SHAPE_KEYS = new Set([
+  "element",
+  "Component",
+  "children",
+  "index",
+  "errorElement",
+  "loader",
+  "action",
+  "lazy",
+]);
+
+// Prefixes with more than one path segment (e.g. "/calendar/api") are a
+// module's own sub-path reservation — the bare root one segment up
+// ("/calendar") is the frontend's by canon, worth saying explicitly. A
+// single-segment prefix ("/admin", "/staticfiles", "/media") is a
+// project-wide infra reservation with no such carve-out.
+const SUBPATH_HINT =
+  "Reserved for the backend (nginx §57 canon). A bare module root (\"/{{mod}}\") stays the frontend's — only this sub-path collides. Route somewhere else, or drop the reservation from reserved-paths.json if this module no longer owns it.";
+const GLOBAL_HINT =
+  "Reserved project-wide for the backend/infra (nginx §57 canon: /admin, /staticfiles, /media) — there is no frontend carve-out for this prefix. Route somewhere else.";
+
+/** A meaningful path: leading "/" plus at least one segment char. */
+function isPathLike(str) {
+  return typeof str === "string" && str.startsWith("/") && /[A-Za-z0-9]/.test(str);
+}
+
+function jsxAttr(node, name) {
+  return node.attributes.find(
+    (a) =>
+      a.type === "JSXAttribute" &&
+      a.name &&
+      a.name.type === "JSXIdentifier" &&
+      a.name.name === name
+  );
+}
+
+/** The literal/template node behind a JSX attribute's value, or null. */
+function jsxAttrValueNode(attr) {
+  if (!attr || attr.value == null) return null;
+  const v = attr.value;
+  if (v.type === "Literal") return v;
+  if (v.type === "JSXExpressionContainer") return v.expression;
+  return null;
+}
+
+/** String literal value, or a template literal's static-prefix, else null. */
+function literalOrTemplatePrefix(node) {
+  if (!node) return null;
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return isPathLike(node.value) ? node.value : null;
+  }
+  if (node.type === "TemplateLiteral" && node.quasis.length > 0) {
+    const head = node.quasis[0].value.cooked ?? node.quasis[0].value.raw ?? "";
+    return isPathLike(head) ? head : null;
+  }
+  return null;
+}
+
+function hasRouteShapeSibling(objExpr) {
+  return objExpr.properties.some(
+    (p) =>
+      p.type === "Property" &&
+      !p.computed &&
+      p.key.type === "Identifier" &&
+      ROUTE_SHAPE_KEYS.has(p.key.name)
+  );
+}
+
+/**
+ * True if `objExpr` sits (through any nesting of `children` arrays / plain
+ * arrays) inside the argument list of a `createBrowserRouter`-family call.
+ */
+function isInRouterFactoryCall(objExpr) {
+  let cur = objExpr;
+  let parent = objExpr.parent;
+  while (parent) {
+    if (parent.type === "ArrayExpression") {
+      cur = parent;
+      parent = parent.parent;
+      continue;
+    }
+    if (
+      parent.type === "Property" &&
+      parent.value === cur &&
+      !parent.computed &&
+      parent.key.type === "Identifier" &&
+      parent.key.name === "children"
+    ) {
+      cur = parent.parent; // the enclosing ObjectExpression
+      parent = cur.parent;
+      continue;
+    }
+    if (parent.type === "CallExpression") {
+      return (
+        parent.arguments.includes(cur) &&
+        parent.callee.type === "Identifier" &&
+        ROUTER_FACTORIES.has(parent.callee.name)
+      );
+    }
+    return false;
+  }
+  return false;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow an SPA route path that falls into a reserved backend sub-path (/<mod>/api/…, /<mod>/swagger…, /admin, /staticfiles, /media). A bare module root is legitimate.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          reservedPathPrefixes: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      reservedSubPath:
+        'Route path "{{path}}" collides with the reserved backend prefix "{{prefix}}". ' +
+        SUBPATH_HINT,
+      reservedGlobal:
+        'Route path "{{path}}" collides with the reserved backend prefix "{{prefix}}". ' +
+        GLOBAL_HINT,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const catalog = loadReservedPathCatalog(
+      context.options[0]?.reservedPathPrefixes
+        ? { reservedPaths: context.options[0].reservedPathPrefixes }
+        : settings
+    );
+    if (!catalog.loaded) return {}; // no reserved-paths.json → no-op, never guess
+
+    function check(node, path) {
+      const prefix = catalog.matches(path);
+      if (!prefix) return;
+      const segments = prefix.split("/").filter(Boolean);
+      const isSubPath = segments.length > 1;
+      const mod = segments[0];
+      context.report({
+        node,
+        messageId: isSubPath ? "reservedSubPath" : "reservedGlobal",
+        data: { path, prefix, mod },
+      });
+    }
+
+    return {
+      // Detector 1: <Route path="…">.
+      JSXOpeningElement(node) {
+        if (!(node.name.type === "JSXIdentifier" && node.name.name === "Route")) return;
+        const attr = jsxAttr(node, "path");
+        const valueNode = jsxAttrValueNode(attr);
+        const path = literalOrTemplatePrefix(valueNode);
+        if (path) check(valueNode, path);
+      },
+      // Detector 2: object route configs (RouteObject shape or a
+      // createBrowserRouter-family array literal).
+      Property(node) {
+        if (
+          node.computed ||
+          node.key.type !== "Identifier" ||
+          node.key.name !== "path" ||
+          node.parent.type !== "ObjectExpression"
+        )
+          return;
+        const path = literalOrTemplatePrefix(node.value);
+        if (!path) return;
+        const objExpr = node.parent;
+        if (!hasRouteShapeSibling(objExpr) && !isInRouterFactoryCall(objExpr)) return;
+        check(node.value, path);
+      },
+    };
+  },
+};