@stapel/eslint-plugin 0.4.0 → 0.5.0

package/README.md

@@ -71,6 +71,7 @@ missing, the rule is a no-op — it never fails the lint run.
 | 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/` |
@@ -103,6 +104,7 @@ settings: {
     eventsManifests: [manifest],// or eventNames: ["pricing.plan.selected", …]
     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";
@@ -24,6 +25,7 @@ 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).
@@ -49,7 +51,7 @@ const rules = {
 };
 
 const plugin = {
-  meta: { name: "@stapel/eslint-plugin", version: "0.1.0" },
+  meta: { name: "@stapel/eslint-plugin", version: "0.5.0" },
   rules,
 };
 
@@ -141,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
@@ -216,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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/eslint-plugin",
-  "version": "0.4.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/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);
+        }
+      },
+    };
+  },
+};