@stapel/eslint-plugin 0.2.0

package/rules/no-string-paths.js

@@ -0,0 +1,168 @@
+// stapel/no-string-paths — frontend-guardrails §2.2 (failure mode F2).
+// API URLs are reached through NAMED operations of the codegen client (layer 2),
+// never a hand-written path string. `client.get("/me/")` (or a bare
+// `"/auth/api/me/"` literal) bypasses the typed operation surface: the wrong
+// verb, a stale path, or a renamed endpoint all pass silently. The recommended
+// preset turns this OFF for the api layer of a pair (`api/`, `*client.ts`,
+// generated) — the ONE legal home of path strings (the operation *definitions*),
+// mirroring the no-raw-fetch carve-out.
+//
+// Two detectors, in the spirit of the other guardrails:
+//   1. Syntactic — a call `<recv>.<verb>("/…")` on an http verb with a
+//      leading-slash string/template path argument (the `client.get("/…")`
+//      bypass shape). Fires with or without a catalog.
+//   2. Data-driven — a string / template path that equals (or, for a
+//      client-relative literal, ends with) a catalogued operation path from a
+//      package manifest.json §operations. A missing catalog degrades detector 2
+//      to a no-op; detector 1 still holds the syntactic line.
+import { loadOperationCatalog, stapelSettings } from "../lib/data.js";
+
+const DEFAULT_HTTP_VERBS = ["get", "post", "put", "patch", "delete", "request"];
+
+const HINT =
+  "Requests go through a NAMED operation of the codegen client, never a path string: const api = createAuthApi(client); await api.<operation>(...). Operations: <pkg>/manifest.json §operations. §2.3 stapel/no-string-paths";
+
+/** A meaningful API path: leading "/" plus at least one segment char. */
+function isPathLike(str) {
+  return str.startsWith("/") && /[A-Za-z0-9]/.test(str);
+}
+
+/** A path-shaped string literal value ("/x/…"), else null. */
+function stringLiteralPath(node) {
+  if (node && node.type === "Literal" && typeof node.value === "string") {
+    return isPathLike(node.value) ? node.value : null;
+  }
+  return null;
+}
+
+/** A template literal whose first quasi begins with "/" — its static prefix. */
+function templatePathPrefix(node) {
+  if (node && 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;
+}
+
+/** Render a template literal back to a readable path with `${…}` placeholders. */
+function templateText(node) {
+  let out = "";
+  node.quasis.forEach((q, i) => {
+    out += q.value.cooked ?? q.value.raw ?? "";
+    if (i < node.expressions.length) out += "${…}";
+  });
+  return out;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow hand-written API path strings (client.<verb>(\"/…\") or a catalogued operation path) outside the codegen API layer.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          verbs: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      // Detector 1 — the client.<verb>("/…") bypass shape.
+      clientPath: 'Hand-written API path "{{path}}" via .{{verb}}(). ' + HINT,
+      // Detector 2 — a literal/template that IS a catalogued operation path.
+      knownPath:
+        'Hand-written API path "{{path}}" — this is the catalogued operation "{{operation}}" of {{pkg}}. ' +
+        HINT,
+      knownPathAnon:
+        'Hand-written API path "{{path}}" — this is a catalogued operation. ' + HINT,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const catalog = loadOperationCatalog(settings);
+    const verbs = new Set(
+      context.options[0]?.verbs ?? settings.httpVerbs ?? DEFAULT_HTTP_VERBS
+    );
+
+    // Nodes already reported by detector 1 (the http-verb call argument), so
+    // detector 2 does not double-report the same string.
+    const reported = new WeakSet();
+
+    function reportKnown(node, path) {
+      const hit = catalog.resolve(path);
+      if (hit && hit.operation) {
+        context.report({
+          node,
+          messageId: "knownPath",
+          data: { path, operation: hit.operation, pkg: hit.pkg ?? "the pair" },
+        });
+      } else {
+        context.report({ node, messageId: "knownPathAnon", data: { path } });
+      }
+      reported.add(node);
+    }
+
+    return {
+      // Detector 1: `<recv>.<verb>(pathArg, …)` on an http verb.
+      CallExpression(node) {
+        const callee = node.callee;
+        if (
+          callee.type !== "MemberExpression" ||
+          callee.computed ||
+          callee.property.type !== "Identifier" ||
+          !verbs.has(callee.property.name)
+        )
+          return;
+        const arg = node.arguments[0];
+        if (!arg) return;
+        const literal = stringLiteralPath(arg);
+        const prefix = literal === null ? templatePathPrefix(arg) : null;
+        if (literal === null && prefix === null) return;
+        const path = literal ?? templateText(arg);
+        context.report({
+          node: arg,
+          messageId: "clientPath",
+          data: { path, verb: callee.property.name },
+        });
+        reported.add(arg);
+      },
+
+      // Detector 2: any literal / template path that IS a catalogued operation.
+      Literal(node) {
+        if (reported.has(node) || !catalog.loaded) return;
+        // A path in object-KEY position is a route / mock-handler table, not a
+        // request — the bypass this rule targets is passing a path to a client
+        // call (detector 1, argument position). Skip keys to avoid flagging
+        // legitimate `{ "/auth/api/me/": handler }` maps (e.g. demo MSW fixtures).
+        if (
+          node.parent &&
+          node.parent.type === "Property" &&
+          !node.parent.computed &&
+          node.parent.key === node
+        )
+          return;
+        const path = stringLiteralPath(node);
+        if (path !== null && catalog.matches(path)) reportKnown(node, path);
+      },
+      TemplateLiteral(node) {
+        if (reported.has(node) || !catalog.loaded) return;
+        if (
+          node.parent &&
+          node.parent.type === "Property" &&
+          node.parent.computed &&
+          node.parent.key === node
+        )
+          return;
+        const prefix = templatePathPrefix(node);
+        // Only flag a template when its STATIC prefix alone is a full catalogued
+        // path (interpolated segments make the rest unknowable — detector 1
+        // already covers `client.get(\`/…/${id}/\`)`).
+        if (prefix !== null && catalog.matches(prefix)) reportKnown(node, prefix);
+      },
+    };
+  },
+};

package/rules/query-keys-from-factory.js

@@ -0,0 +1,143 @@
+// stapel/query-keys-from-factory — frontend-guardrails §2.2 (core gap #8).
+// TanStack Query keys come ONLY from the module's key factory (`<module>QueryKeys`
+// — e.g. `authQueryKeys.sessions()`). A hand-rolled inline array (`queryKey:
+// ["auth","sessions"]`) is the classic drift source: it silently stops matching
+// the factory the mutations invalidate against, so a write updates the server
+// but the screen keeps a stale cache. The rule is a heuristic over the query
+// surface: a call to `useQuery`/`useMutation`/… or a `queryClient.*` method with
+// an INLINE array key. The recommended preset turns it OFF in the factory file
+// itself (`**/queryKeys.*`), where the literal arrays legitimately live.
+import { stapelSettings } from "../lib/data.js";
+
+// Hooks whose options object carries `queryKey` / `mutationKey`.
+const DEFAULT_QUERY_HOOKS = [
+  "useQuery",
+  "useQueries",
+  "useInfiniteQuery",
+  "useSuspenseQuery",
+  "useSuspenseQueries",
+  "useSuspenseInfiniteQuery",
+  "usePrefetchQuery",
+  "usePrefetchInfiniteQuery",
+  "useMutation",
+  "useIsFetching",
+  "useIsMutating",
+  "useMutationState",
+];
+
+// QueryClient methods that take a key — as `{ queryKey: … }` (filters) or as a
+// leading positional array (setQueryData/getQueryData/…).
+const DEFAULT_CLIENT_METHODS = [
+  "invalidateQueries",
+  "removeQueries",
+  "cancelQueries",
+  "refetchQueries",
+  "resetQueries",
+  "isFetching",
+  "prefetchQuery",
+  "prefetchInfiniteQuery",
+  "fetchQuery",
+  "fetchInfiniteQuery",
+  "ensureQueryData",
+  "ensureInfiniteQueryData",
+  "getQueryData",
+  "getQueryState",
+  "setQueryData",
+  "getQueriesData",
+  "setQueriesData",
+];
+
+// Methods whose FIRST positional argument is the key itself (not an options obj).
+const POSITIONAL_KEY_METHODS = new Set([
+  "getQueryData",
+  "getQueryState",
+  "setQueryData",
+  "getQueriesData",
+  "setQueriesData",
+]);
+
+const KEY_PROPS = new Set(["queryKey", "mutationKey"]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require react-query keys to come from the module's key factory, not an inline array literal.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          queryHooks: { type: "array", items: { type: "string" } },
+          clientMethods: { type: "array", items: { type: "string" } },
+          factorySuffix: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      inlineKey:
+        'Inline {{prop}} array. Query keys come only from the module key factory ({{factory}}): {{prop}}: authQueryKeys.<resource>(…). A hand-rolled array drifts from the invalidations that target the factory — the write lands, the cache goes stale. Factory: <module>/model/queryKeys.ts. §2.2 stapel/query-keys-from-factory',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const opt = context.options[0] ?? {};
+    const queryHooks = new Set(
+      opt.queryHooks ?? settings.queryHooks ?? DEFAULT_QUERY_HOOKS
+    );
+    const clientMethods = new Set(
+      opt.clientMethods ?? settings.queryClientMethods ?? DEFAULT_CLIENT_METHODS
+    );
+    const factory = opt.factorySuffix ?? settings.keyFactorySuffix ?? "<module>QueryKeys";
+
+    function report(node, prop) {
+      context.report({ node, messageId: "inlineKey", data: { prop, factory } });
+    }
+
+    /** Report a `queryKey`/`mutationKey: [ … ]` inline array in an options obj. */
+    function checkOptionsObject(objExpr) {
+      if (!objExpr || objExpr.type !== "ObjectExpression") return;
+      for (const p of objExpr.properties) {
+        if (
+          p.type === "Property" &&
+          !p.computed &&
+          p.key.type === "Identifier" &&
+          KEY_PROPS.has(p.key.name) &&
+          p.value.type === "ArrayExpression"
+        ) {
+          report(p.value, p.key.name);
+        }
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee;
+        // useQuery({ queryKey: [...] }) — identifier hook.
+        if (callee.type === "Identifier" && queryHooks.has(callee.name)) {
+          for (const a of node.arguments) checkOptionsObject(a);
+          return;
+        }
+        // queryClient.invalidateQueries({ queryKey: [...] }) / setQueryData([...], …)
+        if (
+          callee.type === "MemberExpression" &&
+          !callee.computed &&
+          callee.property.type === "Identifier" &&
+          clientMethods.has(callee.property.name)
+        ) {
+          const method = callee.property.name;
+          if (POSITIONAL_KEY_METHODS.has(method)) {
+            const first = node.arguments[0];
+            if (first && first.type === "ArrayExpression") report(first, "queryKey");
+            // setQueriesData/getQueriesData also accept a filters object.
+            for (const a of node.arguments) checkOptionsObject(a);
+          } else {
+            for (const a of node.arguments) checkOptionsObject(a);
+          }
+        }
+      },
+    };
+  },
+};

package/rules/require-disable-description.js

@@ -0,0 +1,60 @@
+// stapel/require-disable-description — frontend-guardrails §2.4.
+// An eslint-disable is a documented decision, not a hole: it must carry a
+// `-- reason`. Self-contained equivalent of
+// @eslint-community/eslint-comments/require-description, so the preset stays
+// dependency-light and the escape-hatch policy is enforced for every rule
+// (including future analytics rules). Disables stay greppable and can flow into
+// the analytics/guardrail reports as "explicitly disabled".
+const DIRECTIVES = [
+  "eslint-disable",
+  "eslint-disable-line",
+  "eslint-disable-next-line",
+  "eslint-enable",
+];
+
+// Matches `<directive> <rules...> -- description`
+function parse(text) {
+  const trimmed = text.trim();
+  const directive = DIRECTIVES.find(
+    (d) => trimmed === d || trimmed.startsWith(d + " ") || trimmed.startsWith(d + "\t")
+  );
+  if (!directive) return null;
+  const rest = trimmed.slice(directive.length);
+  const sep = rest.indexOf("--");
+  const description = sep === -1 ? "" : rest.slice(sep + 2).trim();
+  return { directive, description };
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Require a `-- reason` description on every eslint-disable directive.",
+    },
+    schema: [],
+    messages: {
+      missing:
+        "`{{directive}}` needs a reason: add `-- why` after the rule (§2.4 escape-hatch policy). Example: // eslint-disable-next-line stapel/no-raw-colors -- brand chrome, pending token.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+    return {
+      Program() {
+        for (const comment of sourceCode.getAllComments()) {
+          const parsed = parse(comment.value);
+          if (!parsed) continue;
+          if (parsed.directive === "eslint-enable") continue;
+          if (parsed.description.length === 0) {
+            context.report({
+              loc: comment.loc,
+              messageId: "missing",
+              data: { directive: parsed.directive },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/stylelint/index.js

@@ -0,0 +1,93 @@
+// @stapel/eslint-plugin/stylelint — the CSS half of the guardrails
+// (frontend-guardrails §2.2 / §4 declaration-strict-value). A self-contained
+// stylelint plugin (no third-party strict-value dependency) enforcing:
+//   • colour properties may ONLY be `var(--stapel-*)` (or CSS-wide keywords) —
+//     the strict-value discipline, scoped to colour;
+//   • no hex / rgb() / hsl() literal anywhere in a declaration value.
+// Both messages teach the one right way and point at the token catalog.
+import stylelint from "stylelint";
+import {
+  HEX_RE,
+  COLOR_FUNC_RE,
+  isColorProperty,
+} from "../lib/colors.js";
+
+const { createPlugin, utils } = stylelint;
+
+const RULE_NAME = "stapel/color-tokens-only";
+const CATALOG = "@stapel/tokens/llms.txt §colors";
+
+const messages = utils.ruleMessages(RULE_NAME, {
+  rawColor: (value) =>
+    `Raw colour "${value}" in CSS. Use a token: var(--stapel-color-<name>). Hex is born only in ramps. Catalog: ${CATALOG}`,
+  notAToken: (prop, value) =>
+    `Colour property "${prop}" must be a token, got "${value}". Use var(--stapel-color-<name>) (or var(--stapel-<component>)). Catalog: ${CATALOG}`,
+});
+
+// CSS-wide keywords + `transparent`/`currentColor` are allowed on colour props.
+const ALLOWED_KEYWORDS = new Set([
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "revert-layer",
+  "transparent",
+  "currentcolor",
+  "none",
+]);
+
+const HEX_G = new RegExp(HEX_RE.source, "gi");
+const FUNC_G = new RegExp(COLOR_FUNC_RE.source, "gi");
+
+function isStapelVarOnly(value) {
+  // Accept a value composed solely of var(--stapel-*) references (+ keywords).
+  const vars = value.match(/var\(\s*--[\w-]+/g) || [];
+  if (vars.length === 0) return false;
+  return vars.every((v) => /var\(\s*--stapel-/.test(v));
+}
+
+const ruleFunction = (primary) => (root, result) => {
+  const validOptions = utils.validateOptions(result, RULE_NAME, {
+    actual: primary,
+    possible: [true, false],
+  });
+  if (!validOptions || !primary) return;
+
+  root.walkDecls((decl) => {
+    const value = decl.value;
+    const prop = decl.prop;
+
+    // 1) No raw hex / colour-function literal anywhere in a value.
+    if (HEX_G.test(value) || FUNC_G.test(value)) {
+      HEX_G.lastIndex = 0;
+      FUNC_G.lastIndex = 0;
+      utils.report({
+        result,
+        ruleName: RULE_NAME,
+        node: decl,
+        message: messages.rawColor(value),
+      });
+      return;
+    }
+
+    // 2) Colour properties must resolve to a stapel token var.
+    if (isColorProperty(prop)) {
+      const v = value.trim().toLowerCase();
+      if (ALLOWED_KEYWORDS.has(v)) return;
+      if (v.startsWith("var(") && isStapelVarOnly(value)) return;
+      // A non-stapel var, a named colour, or any other literal on a colour prop.
+      utils.report({
+        result,
+        ruleName: RULE_NAME,
+        node: decl,
+        message: messages.notAToken(prop, value),
+      });
+    }
+  });
+};
+
+ruleFunction.ruleName = RULE_NAME;
+ruleFunction.messages = messages;
+
+export default createPlugin(RULE_NAME, ruleFunction);
+export { RULE_NAME, messages };

package/stylelint/preset.js

@@ -0,0 +1,14 @@
+// Stylelint preset (frontend-guardrails §2.2). Drop into a host's
+// stylelint.config.js:
+//
+//   import stapelPreset from "@stapel/eslint-plugin/stylelint/preset";
+//   export default { ...stapelPreset };
+//
+// Enables the self-contained colour-tokens-only rule (no hex/rgb/hsl in CSS;
+// colour properties only via var(--stapel-*)).
+export default {
+  plugins: ["@stapel/eslint-plugin/stylelint"],
+  rules: {
+    "stapel/color-tokens-only": true,
+  },
+};