@stapel/eslint-plugin 0.3.0 → 0.5.0

package/README.md

@@ -38,11 +38,40 @@ 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 |
 |---|---|
 | `stapel/no-raw-colors` | hex/rgb/hsl/named colours in style objects & CSS templates; Tailwind arbitrary colour values `bg-[#…]`; arbitrary values built by interpolation `bg-[${x}]` (JIT-invisible); bare raw-ramp refs `gray.500` |
+| `stapel/valid-token-name` | `cssVar("…")` / `var(--stapel-…)` naming a colour-token role absent from the live `@stapel/tokens` catalog (§68) — a renamed/removed legacy role (`accent`, `background-*-subtle`, the old L3 component tier, …) or a plain typo. Suggests the nearest catalog role when one is close. Non-colour scale suffixes (`radius-*`, `space-*`, `font-*`, `breakpoint-*`, `elevation-*`) are a different vocabulary and never flagged. Extend the recognised call names via `options.functions` or `settings.stapel.cssVarFunctions` (default `["cssVar"]`) |
 | `stapel/no-raw-token-import` | importing `@stapel/tokens/raw` outside theme-config / showcase |
 | `stapel/no-raw-fetch` | `fetch` / `globalThis.fetch` / `new XMLHttpRequest()` / `axios` / `ky` outside the codegen client |
 | `stapel/no-string-paths` | a hand-written API path — `client.get("/…")` on an http verb, or a bare literal/template that IS a catalogued operation path (`manifest.json §operations`) — outside the codegen api layer. Call the named operation instead. Off in `api/`, `*client.ts`, `generated/` |
@@ -58,6 +87,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 +102,9 @@ 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", …]
+    cssVarFunctions: ["cssVar"], // extra token-accessor calls valid-token-name inspects
     httpVerbs: ["get","post"],   // client methods no-string-paths inspects
     queryHooks: ["useQuery"],    // extra react-query hooks to inspect for keys
     trackedWrappers: ["tracked"],

package/index.js

@@ -5,6 +5,7 @@
 // `recommended` preset; the stylelint preset lives at @stapel/eslint-plugin/
 // stylelint.
 import noRawColors from "./rules/no-raw-colors.js";
+import validTokenName from "./rules/valid-token-name.js";
 import noRawTokenImport from "./rules/no-raw-token-import.js";
 import noRawFetch from "./rules/no-raw-fetch.js";
 import noStringPaths from "./rules/no-string-paths.js";
@@ -20,9 +21,11 @@ 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,
+  "valid-token-name": validTokenName,
   "no-raw-token-import": noRawTokenImport,
   "no-raw-fetch": noRawFetch,
   // Server-state guardrails (frontend-guardrails §2.2 / §2.6).
@@ -42,10 +45,13 @@ 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 = {
-  meta: { name: "@stapel/eslint-plugin", version: "0.1.0" },
+  meta: { name: "@stapel/eslint-plugin", version: "0.5.0" },
   rules,
 };
 
@@ -137,6 +143,7 @@ const recommended = [
     files: TS_JS,
     rules: {
       "stapel/no-raw-colors": "error",
+      "stapel/valid-token-name": "error",
       "stapel/no-raw-token-import": "error",
       "stapel/no-raw-fetch": "error",
       // Server state: reach endpoints through named operations, keys through the
@@ -160,6 +167,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",
     },
   },
   {
@@ -208,6 +219,7 @@ const recommended = [
     files: TEST_FILES,
     rules: {
       "stapel/no-raw-colors": "off",
+      "stapel/valid-token-name": "off",
       "stapel/no-hardcoded-text": "off",
       "stapel/i18n-key-exists": "off",
       "stapel/no-raw-fetch": "off",
@@ -227,6 +239,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.5.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.4.0"
+    "@stapel/tokens": "^0.5.0"
   },
   "peerDependencies": {
     "eslint": ">=9",

package/rules/no-raw-colors.js

@@ -48,10 +48,10 @@ export default {
     schema: [],
     messages: {
       rawColor:
-        'Raw colour "{{value}}". Use a token: in TS — cssVar("color-{{suggest}}"), in CSS — var(--stapel-color-{{suggest}}), in Tailwind — a token utility (e.g. bg-background-primary). Hex is born only in ramps. Catalog: ' +
+        'Raw colour "{{value}}". Use a token: in TS — cssVar("{{suggest}}"), in CSS — var(--stapel-{{suggest}}), in Tailwind — a token utility (e.g. bg-surface). Hex is born only in ramps. Catalog: ' +
         LLMS,
       arbitraryColor:
-        'Tailwind arbitrary colour "[{{value}}]". Use a token utility (e.g. bg-background-primary / text-text-primary) instead of a raw value in [...]. Catalog: ' +
+        'Tailwind arbitrary colour "[{{value}}]". Use a token utility (e.g. bg-surface / text-text) instead of a raw value in [...]. Catalog: ' +
         LLMS,
       arbitraryInterpolation:
         'Tailwind arbitrary value built by interpolation ("{{value}}"). The JIT scanner sees the literal source text, not the resolved value, so no utility is emitted — works in dev, breaks in prod. Use a static token utility. Catalog: ' +
@@ -70,7 +70,7 @@ export default {
       context.report({
         node,
         messageId: "rawColor",
-        data: { value: String(raw).slice(0, 40), suggest: "accent" },
+        data: { value: String(raw).slice(0, 40), suggest: "brand" },
       });
     }
 

package/rules/no-raw-token-import.js

@@ -24,7 +24,7 @@ export default {
     ],
     messages: {
       rawImport:
-        'Import from "{{source}}" is raw-ramp access (L1 hex). Only the theme config and the design-system showcase may import it — component code references tokens: cssVar("color-…") / var(--stapel-color-…). See @stapel/tokens/llms.txt §Never.',
+        'Import from "{{source}}" is raw-ramp access (L1 hex). Only the theme config and the design-system showcase may import it — component code references tokens: cssVar("brand") / var(--stapel-brand). See @stapel/tokens/llms.txt §Never.',
     },
   },
   create(context) {

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

package/rules/valid-token-name.js

@@ -0,0 +1,157 @@
+// stapel/valid-token-name — frontend-guardrails §68 (colour-token canon).
+// A `cssVar("<name>")` call or a `var(--stapel-<name>)` CSS reference must
+// name a ROLE that exists in the live token catalog
+// (@stapel/tokens/manifest.json `tokens.core`/`tokens.component`). Both
+// failure modes this catches resolve SILENTLY at runtime instead of failing
+// loudly — an unset custom property just falls through to `initial`/inherit,
+// so the wrong colour (or no colour) never shows up as an error:
+//   - a RENAMED/REMOVED legacy role: the §68 neutral-dictionary migration
+//     deleted `accent`, `background-*-subtle`, `upperground-*`, `icon-*`,
+//     `text-invert`, `overlay`, and the whole L3 component tier
+//     (`button-primary-bg`, `card-bg`, ...) with no compatibility alias.
+//   - a plain typo in an otherwise-valid role name.
+// Data-driven (§2.1): reads the SAME catalog no-raw-colors reads. No catalog
+// → no-op, never guess (never crashes the lint run).
+//
+// Scoped to COLOUR roles only. `cssVar()`'s real type (`StapelVar`) also
+// accepts a stable, unrelated set of scale suffixes this rule does not police
+// — `font-family-*` / `font-size-*` / `font-weight-*` / `line-height-*` /
+// `radius-*` / `space-*` / `breakpoint-*` / `elevation-*` — skipped by prefix
+// so a legitimate `cssVar("radius-md")` never false-positives.
+import { loadTokenCatalog, stapelSettings } from "../lib/data.js";
+
+const LLMS = "@stapel/tokens/llms.txt §colors";
+
+const DEFAULT_FUNCTIONS = ["cssVar"];
+
+// Non-colour scale namespaces this rule never validates (see header).
+const SCALE_PREFIXES = [
+  "font-family-",
+  "font-size-",
+  "font-weight-",
+  "line-height-",
+  "radius-",
+  "space-",
+  "breakpoint-",
+  "elevation-",
+];
+
+function isScaleName(name) {
+  return SCALE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+// var(--stapel-<name>) or var(--stapel-<name>, <fallback>) — captures <name>.
+const VAR_RE = /var\(\s*--stapel-([a-zA-Z0-9-]+)\s*(?:,[^)]*)?\)/g;
+
+/** Plain Levenshtein edit distance — small inputs (token role names), O(mn) is fine. */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = [];
+  for (let i = 0; i <= m; i++) dp.push([i, ...new Array(n).fill(0)]);
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/** Nearest catalog name, or null when nothing is plausibly the same word. */
+function closestName(name, names) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const candidate of names) {
+    const d = levenshtein(name, candidate);
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  const threshold = Math.max(3, Math.ceil(name.length / 2));
+  return best !== null && bestDist <= threshold ? best : null;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow cssVar()/var(--stapel-*) references to a colour-token role absent from the live @stapel/tokens catalog.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          functions: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      unknownToken:
+        'Unknown token role "{{name}}" ({{form}}). It is not in the live @stapel/tokens catalog{{suggestion}}. Legacy/renamed roles do not alias — reference a current role. Catalog: ' +
+        LLMS,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const catalog = loadTokenCatalog(settings);
+    if (!catalog.loaded) return {}; // no manifest → no-op, never guess
+
+    const functions = new Set(
+      context.options[0]?.functions ?? settings.cssVarFunctions ?? DEFAULT_FUNCTIONS
+    );
+    const names = [...catalog.all];
+
+    function reportIfUnknown(node, name, form) {
+      if (isScaleName(name)) return;
+      if (catalog.hasToken(name)) return;
+      const suggestion = closestName(name, names);
+      context.report({
+        node,
+        messageId: "unknownToken",
+        data: {
+          name,
+          form,
+          suggestion: suggestion ? ` — did you mean "${suggestion}"?` : "",
+        },
+      });
+    }
+
+    function scanForVarRefs(node, text) {
+      VAR_RE.lastIndex = 0;
+      let m;
+      while ((m = VAR_RE.exec(text)) !== null) {
+        reportIfUnknown(node, m[1], "var(--stapel-*)");
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || !functions.has(node.callee.name))
+          return;
+        const arg = node.arguments[0];
+        if (arg && arg.type === "Literal" && typeof arg.value === "string") {
+          reportIfUnknown(arg, arg.value, "cssVar()");
+        }
+      },
+      // Plain string literals: `"var(--stapel-accent)"` in a style object,
+      // a plain assignment, a JSX attribute string, etc.
+      Literal(node) {
+        if (typeof node.value === "string") scanForVarRefs(node, node.value);
+      },
+      // Template literals (including CSS-in-JS tagged templates — ESLint
+      // visits the TemplateLiteral itself regardless of the tag).
+      TemplateLiteral(node) {
+        for (const q of node.quasis) {
+          scanForVarRefs(node, q.value.cooked ?? q.value.raw);
+        }
+      },
+    };
+  },
+};