@stapel/eslint-plugin 0.3.0 → 0.4.0

package/README.md

@@ -38,6 +38,34 @@ The `recommended` preset:
 - **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 |
@@ -58,6 +86,7 @@ The `recommended` preset:
 | `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
 
@@ -72,7 +101,8 @@ settings: {
     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

@@ -20,6 +20,7 @@ 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,
@@ -42,6 +43,9 @@ const rules = {
   // 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 = {
@@ -160,6 +164,10 @@ const recommended = [
       // + 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",
     },
   },
   {
@@ -227,6 +235,9 @@ const recommended = [
       // 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.3.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": {

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);
+      },
+    };
+  },
+};