@stapel/eslint-plugin 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @stapel/eslint-plugin
+
+The enforcement tier of the Stapel frontend guardrails (frontend-guardrails §2):
+static lint rules that close the bypass paths a design system leaves open. Every
+rule is **data-driven** — it reads the same generated manifests the codegen
+writes (`@stapel/tokens/manifest.json`, pair i18n key registries), so lint and
+code never drift. Error messages **teach**: what's wrong, what to do instead, and
+where the catalog lives.
+
+## Install
+
+```sh
+pnpm add -D @stapel/eslint-plugin
+```
+
+## Flat config
+
+```js
+// eslint.config.mjs
+import tseslint from "typescript-eslint";
+import stapel from "@stapel/eslint-plugin";
+
+export default [
+  ...tseslint.configs.strict,
+  ...stapel.configs.recommended, // spread LAST — its file overrides must win
+];
+```
+
+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.*`);
+- **overrides** the content rules off in tests and fixtures (they exercise the
+  anti-patterns on purpose).
+
+## 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/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/` |
+| `stapel/query-keys-from-factory` | an inline `queryKey`/`mutationKey` array literal in `useQuery`/`useMutation`/`queryClient.*` — keys come only from the module's `<module>QueryKeys` factory (drift from invalidations otherwise). Off in the factory file (`**/queryKeys.*`) |
+| `stapel/i18n-key-exists` | `t("…")` keys absent from the generated registry (only within a managed namespace — app-local keys are left alone) |
+| `stapel/no-hardcoded-text` | user-facing JSX text and `alt`/`title`/`placeholder`/`aria-*` string literals |
+| `stapel/require-disable-description` | an `eslint-disable` without a `-- reason` (§2.4 escape-hatch policy) |
+| `stapel/clickable-needs-event` | an interactive JSX element (`onClick`/`onSubmit`/…) with no analytics outcome — needs `tracked()`/`trackedSubmit()`, `data-analytics="flow"`, or `data-analytics="none"` + a reason (§3.2). Decorative `stopPropagation`/`preventDefault`-only handlers are exempt |
+| `stapel/no-double-count` | `tracked()`/`trackedSubmit()` over a handler that also steps a flow machine (`run`/`step`/`submit*`, or `data-analytics="flow"` on the same element) — the funnel already auto-emits (hard ban, Q12а / §3.2) |
+| `stapel/event-literal-meta` | `defineEvent()` with a non-literal argument (dynamic `name`/`description`, non-`prop.*` props) — breaks static extraction into `events.json` (§3.1) |
+| `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) |
+
+### Settings
+
+Rules resolve their catalogs automatically; override for non-standard layouts:
+
+```js
+settings: {
+  stapel: {
+    tokensManifest: {...},      // or tokensManifestPath
+    i18nKeys: ["auth.otp.…"],   // or i18nManifests: [manifest, …]
+    httpModules: ["my-http"],   // extra banned HTTP clients
+    rawModules: ["@x/raw"],     // extra raw-token entry points
+    eventsManifests: [manifest],// or eventNames: ["pricing.plan.selected", …]
+    operationsManifests: [manifest], // or operationPaths: ["/auth/api/me/", …]
+    httpVerbs: ["get","post"],   // client methods no-string-paths inspects
+    queryHooks: ["useQuery"],    // extra react-query hooks to inspect for keys
+    trackedWrappers: ["tracked"],
+    clickHandlers: ["onClick"], // extra interactive handler props
+  },
+}
+```
+
+## Stylelint preset
+
+A self-contained stylelint plugin (no third-party strict-value dependency): colour
+properties may only be `var(--stapel-*)`, and no hex/rgb/hsl literal is allowed in
+any declaration.
+
+```js
+// stylelint.config.js
+import stapelPreset from "@stapel/eslint-plugin/stylelint/preset";
+export default { ...stapelPreset };
+```

package/index.js

@@ -0,0 +1,194 @@
+// @stapel/eslint-plugin — the enforcement tier of the frontend guardrails
+// (frontend-guardrails §2). Rules are data-driven: they read the same generated
+// manifests (@stapel/tokens/manifest.json, pair i18n key registries) the
+// codegen writes, so lint and code never drift. Ships a flat-config
+// `recommended` preset; the stylelint preset lives at @stapel/eslint-plugin/
+// stylelint.
+import noRawColors from "./rules/no-raw-colors.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";
+import queryKeysFromFactory from "./rules/query-keys-from-factory.js";
+import i18nKeyExists from "./rules/i18n-key-exists.js";
+import noHardcodedText from "./rules/no-hardcoded-text.js";
+import requireDisableDescription from "./rules/require-disable-description.js";
+import clickableNeedsEvent from "./rules/clickable-needs-event.js";
+import noDoubleCount from "./rules/no-double-count.js";
+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";
+
+const rules = {
+  "no-raw-colors": noRawColors,
+  "no-raw-token-import": noRawTokenImport,
+  "no-raw-fetch": noRawFetch,
+  // Server-state guardrails (frontend-guardrails §2.2 / §2.6).
+  "no-string-paths": noStringPaths,
+  "query-keys-from-factory": queryKeysFromFactory,
+  "i18n-key-exists": i18nKeyExists,
+  "no-hardcoded-text": noHardcodedText,
+  "require-disable-description": requireDisableDescription,
+  // Typed-analytics guardrails (frontend-guardrails §3, task G4).
+  "clickable-needs-event": clickableNeedsEvent,
+  "no-double-count": noDoubleCount,
+  "event-literal-meta": eventLiteralMeta,
+  "known-event": knownEvent,
+  "no-direct-analytics-provider": noDirectAnalyticsProvider,
+  // Showcase guardrail (frontend-guardrails §4, task G7).
+  "demo-literal-meta": demoLiteralMeta,
+};
+
+const plugin = {
+  meta: { name: "@stapel/eslint-plugin", version: "0.1.0" },
+  rules,
+};
+
+const TS_JS = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
+const JSX = ["**/*.{tsx,jsx}"];
+
+// Tests and fixtures legitimately exercise the anti-patterns these rules
+// forbid — raw ramps as validator input, deliberately-unknown i18n keys,
+// throwaway JSX copy — so the guardrails are scoped off there. Product source,
+// demos (`demo/`), and the showcase stay covered.
+const TEST_FILES = [
+  "**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+  "**/test/**",
+  "**/tests/**",
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/fixtures/**",
+  "**/*.fixture.{ts,tsx,js,jsx}",
+];
+
+// Files that are ALLOWED to reach the raw ramps (theme config + showcase +
+// build scripts) — no-raw-token-import is off here (§2.2 overrides).
+const RAW_ALLOWED = [
+  "**/theme/**",
+  "**/*.theme.{ts,tsx,js,mjs,json}",
+  "**/stapel.theme.*",
+  "**/tokens/**",
+  "**/demo/**",
+  "**/demos/**",
+  "**/*.demo.{ts,tsx,jsx}",
+  "**/showcase/**",
+  "**/scripts/**",
+  "**/*.stories.{ts,tsx,jsx}",
+];
+
+// The codegen API layer — the one legal home of fetch (§2.2 override).
+const FETCH_ALLOWED = [
+  "**/api/**",
+  "**/*client.{ts,js}",
+  "**/analytics/providers.{ts,js}",
+  "**/scripts/**",
+];
+
+// The codegen API layer — the one legal home of path STRINGS (the operation
+// definitions themselves), mirroring the fetch carve-out (§2.2 override).
+const PATHS_ALLOWED = [
+  "**/api/**",
+  "**/*client.{ts,js}",
+  "**/generated/**",
+  "**/scripts/**",
+];
+
+// The query-key factory file — where the literal key arrays legitimately live
+// (§2.2 override; the rest of the pair/app must reach them through the factory).
+const KEY_FACTORY = [
+  "**/queryKeys.{ts,tsx,js,mjs}",
+  "**/*QueryKeys.{ts,tsx,js,mjs}",
+  "**/query-keys.{ts,tsx,js,mjs}",
+];
+
+/**
+ * Flat-config `recommended` preset. Consumers spread it AFTER their parser
+ * config:
+ *
+ *   import stapel from "@stapel/eslint-plugin";
+ *   export default [ ...tseslint.configs.strict, ...stapel.configs.recommended ];
+ */
+const recommended = [
+  { plugins: { stapel: plugin } },
+  {
+    files: TS_JS,
+    rules: {
+      "stapel/no-raw-colors": "error",
+      "stapel/no-raw-token-import": "error",
+      "stapel/no-raw-fetch": "error",
+      // Server state: reach endpoints through named operations, keys through the
+      // factory (§2.2 / §2.6). Both carved out in their one legal home below.
+      "stapel/no-string-paths": "error",
+      "stapel/query-keys-from-factory": "error",
+      "stapel/i18n-key-exists": "error",
+      "stapel/require-disable-description": "error",
+      // Typed analytics (§3). Literal-meta keeps events statically extractable;
+      // double-count is a hard ban (Q12а); known-event is drift → warn (goes
+      // green after `pnpm gen:events`). These fire on .ts (defineEvent, track).
+      "stapel/event-literal-meta": "error",
+      "stapel/no-double-count": "error",
+      "stapel/known-event": "warn",
+      // Vendor SDKs only behind the core facade (§2.2 / F9).
+      "stapel/no-direct-analytics-provider": "error",
+      // Showcase (§4): defineDemo meta must stay literal (extractable).
+      "stapel/demo-literal-meta": "error",
+    },
+  },
+  {
+    files: JSX,
+    rules: {
+      "stapel/no-hardcoded-text": "error",
+      // Clickable-without-an-outcome is a JSX concern (§3.2).
+      "stapel/clickable-needs-event": "error",
+    },
+  },
+  {
+    files: RAW_ALLOWED,
+    rules: { "stapel/no-raw-token-import": "off" },
+  },
+  {
+    files: FETCH_ALLOWED,
+    rules: { "stapel/no-raw-fetch": "off" },
+  },
+  {
+    files: PATHS_ALLOWED,
+    rules: { "stapel/no-string-paths": "off" },
+  },
+  {
+    files: KEY_FACTORY,
+    rules: { "stapel/query-keys-from-factory": "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/**"],
+    rules: { "stapel/no-direct-analytics-provider": "off" },
+  },
+  {
+    files: TEST_FILES,
+    rules: {
+      "stapel/no-raw-colors": "off",
+      "stapel/no-hardcoded-text": "off",
+      "stapel/i18n-key-exists": "off",
+      "stapel/no-raw-fetch": "off",
+      "stapel/no-string-paths": "off",
+      "stapel/query-keys-from-factory": "off",
+      "stapel/no-raw-token-import": "off",
+      // Fixtures / headless test factories legitimately train the analytics
+      // anti-patterns (dynamic defineEvent, deliberate double-count, unknown
+      // events, un-tracked clickables) — off there, on in product/demos.
+      "stapel/clickable-needs-event": "off",
+      "stapel/event-literal-meta": "off",
+      "stapel/no-double-count": "off",
+      "stapel/known-event": "off",
+      "stapel/no-direct-analytics-provider": "off",
+      "stapel/demo-literal-meta": "off",
+      // require-disable-description stays ON — disable hygiene applies everywhere.
+    },
+  },
+];
+
+plugin.configs = { recommended };
+
+export default plugin;
+export { rules, recommended };

package/lib/colors.js

@@ -0,0 +1,73 @@
+// Colour-syntax detection shared by no-raw-colors (ESLint) and the stylelint
+// preset. Kept deliberately narrow so it only fires in colour CONTEXTS
+// (style-object values, className arbitrary values, CSS templates) — never on
+// arbitrary strings — to keep false positives near zero (frontend-guardrails
+// §1.5: the anti-pattern is a hardcoded hex in a styled surface, not the
+// substring "#abc" in an anchor href).
+
+// #rgb, #rgba, #rrggbb, #rrggbbaa
+export const HEX_RE = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})(?![0-9a-fA-F])/;
+// rgb()/rgba()/hsl()/hsla() function syntax
+export const COLOR_FUNC_RE = /\b(?:rgba?|hsla?)\s*\(/i;
+
+// A curated set of CSS named colours. Only checked when the value is the WHOLE
+// value of a colour property (style objects / CSS decls), so "red" as an
+// identifier or a word inside prose is never touched.
+export const NAMED_COLORS = new Set([
+  "black", "white", "red", "green", "blue", "yellow", "orange", "purple",
+  "pink", "gray", "grey", "cyan", "magenta", "lime", "teal", "navy", "maroon",
+  "olive", "silver", "gold", "indigo", "violet", "coral", "salmon", "crimson",
+  "turquoise", "beige", "tan", "brown", "aqua", "fuchsia",
+]);
+
+// CSS/React style property keys that carry a colour. Used to gate NAMED colours
+// and to know a style value is colour-ish. Anything ending in "color" counts,
+// plus these composite properties.
+const COLOR_PROP_EXTRA = new Set([
+  "background", "border", "outline", "fill", "stroke", "boxShadow",
+  "textShadow", "borderTop", "borderRight", "borderBottom", "borderLeft",
+  "box-shadow", "text-shadow", "border-top", "border-right", "border-bottom",
+  "border-left",
+]);
+
+export function isColorProperty(key) {
+  if (typeof key !== "string") return false;
+  const k = key.trim();
+  return /color$/i.test(k) || COLOR_PROP_EXTRA.has(k);
+}
+
+/** Any hex or colour-function token in a string (context already colour-ish). */
+export function hasColorSyntax(value) {
+  return HEX_RE.test(value) || COLOR_FUNC_RE.test(value);
+}
+
+/** Whole-value named colour (e.g. a style value of exactly "red"). */
+export function isNamedColorValue(value) {
+  return NAMED_COLORS.has(String(value).trim().toLowerCase());
+}
+
+/**
+ * Scan a className string for Tailwind arbitrary values that embed a raw
+ * colour: `bg-[#4657d9]`, `text-[rgb(...)]`, `border-[gray.500]`. Returns the
+ * first offending fragment or null. `rampNames` lets us flag raw-ramp refs
+ * (`gray.500`) that slipped into an arbitrary value.
+ */
+export function findArbitraryColor(className, rampNames) {
+  const re = /(?:^|[\s])[\w-]*\[([^\]]*)\]/g;
+  let m;
+  while ((m = re.exec(className)) !== null) {
+    const inner = m[1];
+    if (hasColorSyntax(inner)) return inner;
+    // raw ramp reference inside the arbitrary value, e.g. bg-[gray.500]
+    const ramp = /^([a-z]+)\.[\w-]+$/i.exec(inner.trim());
+    if (ramp && rampNames && rampNames.has(ramp[1])) return inner;
+  }
+  return null;
+}
+
+/** True when a string looks like a bare raw-ramp reference: `<ramp>.<step>`. */
+export function matchRampRef(value, rampNames) {
+  const m = /^([a-z]+)\.[\w-]+$/i.exec(String(value).trim());
+  if (m && rampNames && rampNames.has(m[1])) return m[1];
+  return null;
+}