@stapel/eslint-plugin 0.2.0

package/rules/no-double-count.js

@@ -0,0 +1,180 @@
+// stapel/no-double-count — frontend-guardrails §3.2 + user decision Q12а
+// (hard ban; overrides open question §7). A flow machine is already
+// auto-instrumented — every transition emits flow.<id>.<step>. Wrapping a
+// handler that ALSO steps that machine in tracked()/trackedSubmit() double-
+// counts the funnel. Exactly one channel is allowed.
+//
+// Two heuristics, both syntactic (§3.2):
+//
+//   1. tracked(event, props, handler) where the handler steps a machine — a
+//      call to a run / step / submit* method inside the handler function.
+//   2. an element that BOTH carries data-analytics="flow" AND wraps its handler
+//      in tracked()/trackedSubmit() — the author asserted the flow channel and
+//      opened a second one.
+//
+// The teaching message is the same in both cases: the flow step already emits
+// the funnel — drop the tracked() wrapper OR the flow marker, keep one channel.
+import { stapelSettings } from "../lib/data.js";
+
+const DEFAULT_WRAPPERS = ["tracked", "trackedSubmit"];
+const DEFAULT_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onSubmit",
+  "onPointerDown",
+  "onPointerUp",
+  "onMouseDown",
+  "onMouseUp",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress",
+  "onTouchStart",
+  "onTouchEnd",
+];
+// Flow-machine stepping methods (frontend-guardrails §3.2 heuristic:
+// "run/step/submit* methods of the machine"). `submit*` matches submit,
+// submitCode, submitForm, …
+const STEP_METHODS = new Set(["run", "step"]);
+const STEP_PREFIX = "submit";
+
+const LESSON =
+  "the flow step already emits the funnel (flow.<id>.<step>) — remove the tracked() wrapper OR the flow marker, keep exactly one channel (Q12а). §3.2 stapel/no-double-count";
+
+function isWrapperCall(node, wrappers) {
+  if (!node || node.type !== "CallExpression") return false;
+  const callee = node.callee;
+  const name =
+    callee.type === "Identifier"
+      ? callee.name
+      : callee.type === "MemberExpression" &&
+          !callee.computed &&
+          callee.property.type === "Identifier"
+        ? callee.property.name
+        : null;
+  return !!name && wrappers.has(name);
+}
+
+function isStepMethodCall(node) {
+  if (
+    node.type !== "CallExpression" ||
+    node.callee.type !== "MemberExpression" ||
+    node.callee.computed ||
+    node.callee.property.type !== "Identifier"
+  )
+    return false;
+  const m = node.callee.property.name;
+  return STEP_METHODS.has(m) || m.startsWith(STEP_PREFIX);
+}
+
+/** Walk `root`'s descendants for a flow-stepping method call. */
+function containsStep(root) {
+  const seen = new Set();
+  const stack = [root];
+  while (stack.length) {
+    const node = stack.pop();
+    if (!node || typeof node !== "object" || seen.has(node)) continue;
+    seen.add(node);
+    if (typeof node.type === "string" && isStepMethodCall(node)) return true;
+    for (const key of Object.keys(node)) {
+      if (key === "parent") continue;
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const c of child) if (c && typeof c === "object") stack.push(c);
+      } else if (child && typeof child === "object" && typeof child.type === "string") {
+        stack.push(child);
+      }
+    }
+  }
+  return false;
+}
+
+function attrName(attr) {
+  return attr.type === "JSXAttribute" && attr.name && attr.name.type === "JSXIdentifier"
+    ? attr.name.name
+    : null;
+}
+
+function attrLiteral(attr) {
+  const v = attr.value;
+  if (v == null) return true;
+  if (v.type === "Literal") return v.value;
+  if (v.type === "JSXExpressionContainer" && v.expression.type === "Literal")
+    return v.expression.value;
+  return undefined;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow tracked()/trackedSubmit() on a handler that also steps a flow machine (double-counting the funnel).",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          wrappers: { type: "array", items: { type: "string" } },
+          handlers: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      trackedStepsFlow: "Double count: tracked() wraps a handler that steps a flow machine — " + LESSON,
+      flowMarkerAndTracked:
+        'Double count: element is marked data-analytics="flow" AND its handler is wrapped in tracked() — ' + LESSON,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const wrappers = new Set(
+      context.options[0]?.wrappers ?? settings.trackedWrappers ?? DEFAULT_WRAPPERS
+    );
+    const handlers = new Set(
+      context.options[0]?.handlers ?? settings.clickHandlers ?? DEFAULT_HANDLERS
+    );
+
+    // tracked() calls already reported via the flow-marker heuristic — skip
+    // them in the CallExpression pass so an element that both marks flow and
+    // steps a machine reports once. JSXOpeningElement is visited before the
+    // CallExpression nested in its attribute (top-down traversal).
+    const reportedViaMarker = new Set();
+
+    return {
+      JSXOpeningElement(node) {
+        let isFlow = false;
+        const wrapperCalls = [];
+        for (const attr of node.attributes) {
+          const name = attrName(attr);
+          if (name === "data-analytics" && attrLiteral(attr) === "flow") isFlow = true;
+          else if (name && handlers.has(name)) {
+            const v = attr.value;
+            const expr = v && v.type === "JSXExpressionContainer" ? v.expression : null;
+            if (isWrapperCall(expr, wrappers)) wrapperCalls.push(expr);
+          }
+        }
+        if (isFlow && wrapperCalls.length) {
+          for (const call of wrapperCalls) {
+            reportedViaMarker.add(call);
+            context.report({ node: call, messageId: "flowMarkerAndTracked" });
+          }
+        }
+      },
+
+      CallExpression(node) {
+        if (!isWrapperCall(node, wrappers)) return;
+        if (reportedViaMarker.has(node)) return;
+        const handler = node.arguments[2];
+        if (!handler) return;
+        if (
+          (handler.type === "ArrowFunctionExpression" ||
+            handler.type === "FunctionExpression") &&
+          containsStep(handler.body)
+        ) {
+          context.report({ node, messageId: "trackedStepsFlow" });
+        }
+      },
+    };
+  },
+};

package/rules/no-hardcoded-text.js

@@ -0,0 +1,99 @@
+// stapel/no-hardcoded-text — frontend-guardrails §2.2 (failure mode F7).
+// User-facing text belongs to an i18n key, never a literal. Catches JSX text
+// nodes and the user-facing string attributes (alt/title/placeholder/aria-*).
+// Heuristic, with a conservative false-positive policy: only strings that read
+// as prose (a run of letters plus a space, or a ≥4-char word) fire — icons,
+// punctuation, numbers, single technical tokens, and camelCase identifiers are
+// left alone.
+import { stapelSettings } from "../lib/data.js";
+
+const USER_FACING_ATTRS = new Set([
+  "alt",
+  "title",
+  "placeholder",
+  "aria-label",
+  "aria-description",
+  "aria-placeholder",
+  "aria-valuetext",
+  "aria-roledescription",
+]);
+
+// Prose = has a letter, and either contains whitespace between word chars or
+// is a single word of length ≥ 4. Rejects "OK"? -> "OK" is 2 letters, no space
+// → not flagged (conservative). "Sign in" → flagged. "px" → not flagged.
+function looksLikeProse(raw) {
+  const s = raw.trim();
+  if (s.length < 3) return false;
+  if (!/[A-Za-zÀ-ɏ]/.test(s)) return false; // no letters → skip
+  if (/^[\d\s.,:;!?%$#@/\\|()[\]{}<>=+*~`^&-]+$/.test(s)) return false; // symbols/nums
+  // camelCase / snake / kebab single identifier with no space → likely technical
+  if (!/\s/.test(s) && /^[a-z][A-Za-z0-9]*$/.test(s) && s.length < 4) return false;
+  if (!/\s/.test(s)) {
+    // single token: require it to be a real-ish word (≥ 4 letters, mostly alpha)
+    const letters = (s.match(/[A-Za-zÀ-ɏ]/g) || []).length;
+    return letters >= 4 && letters / s.length > 0.6;
+  }
+  return true;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow hardcoded user-facing text in JSX; use an i18n key.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          ignore: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      hardcoded:
+        'Hardcoded user-facing text "{{text}}". Add an i18n key and render it via t("<key>") instead of a literal. Convention: @stapel/core/llms.txt §i18n.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const ignore = new Set([
+      ...(settings.textIgnore ?? []),
+      ...(context.options[0]?.ignore ?? []),
+    ]);
+
+    function maybeReport(node, raw) {
+      const text = String(raw);
+      if (ignore.has(text.trim())) return;
+      if (!looksLikeProse(text)) return;
+      context.report({
+        node,
+        messageId: "hardcoded",
+        data: { text: text.trim().slice(0, 40) },
+      });
+    }
+
+    return {
+      JSXText(node) {
+        maybeReport(node, node.value);
+      },
+      JSXAttribute(node) {
+        const name = node.name && node.name.name;
+        if (typeof name !== "string" || !USER_FACING_ATTRS.has(name)) return;
+        const val = node.value;
+        if (val && val.type === "Literal" && typeof val.value === "string") {
+          maybeReport(val, val.value);
+        } else if (
+          val &&
+          val.type === "JSXExpressionContainer" &&
+          val.expression.type === "Literal" &&
+          typeof val.expression.value === "string"
+        ) {
+          maybeReport(val.expression, val.expression.value);
+        }
+      },
+    };
+  },
+};

package/rules/no-raw-colors.js

@@ -0,0 +1,197 @@
+// stapel/no-raw-colors — frontend-guardrails §2.2.
+// Raw colours (hex/rgb/hsl/named) in styled surfaces, and Tailwind arbitrary
+// values that embed a colour, are the cheapest token for an LLM to hardcode
+// (§F7). Hex is born in exactly one place — the ramps — and everything above
+// references tokens. Message teaches the one right way + points at the catalog.
+import { loadTokenCatalog, stapelSettings } from "../lib/data.js";
+import {
+  hasColorSyntax,
+  isColorProperty,
+  isNamedColorValue,
+  findArbitraryColor,
+  matchRampRef,
+} from "../lib/colors.js";
+
+const LLMS = "@stapel/tokens/llms.txt §colors";
+
+const CSS_TAGS = new Set([
+  "css",
+  "styled",
+  "createGlobalStyle",
+  "keyframes",
+  "injectGlobal",
+]);
+
+function isCssTag(tag) {
+  if (!tag) return false;
+  if (tag.type === "Identifier") return CSS_TAGS.has(tag.name);
+  // styled.div`...`, styled(Comp)`...`
+  if (tag.type === "MemberExpression" && tag.object?.name === "styled")
+    return true;
+  if (tag.type === "CallExpression" && tag.callee?.name === "styled")
+    return true;
+  return false;
+}
+
+/** name of a className-ish JSX attribute */
+function isClassNameAttr(name) {
+  return name === "className" || name === "class";
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow raw colour literals and Tailwind arbitrary colour values; use design tokens.",
+    },
+    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: ' +
+        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: ' +
+        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: ' +
+        LLMS,
+      rawRamp:
+        'Raw ramp reference "{{value}}". Ramps ({{ramp}}.*) are L1 and not for component code — reference a token instead. Catalog: ' +
+        LLMS,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const catalog = loadTokenCatalog(settings);
+    const ramps = catalog.ramps;
+
+    function reportColorValue(node, raw) {
+      context.report({
+        node,
+        messageId: "rawColor",
+        data: { value: String(raw).slice(0, 40), suggest: "accent" },
+      });
+    }
+
+    // Style objects: JSX style={{...}} and any object literal property whose
+    // key is a colour property with a raw colour value.
+    function checkStyleProperty(prop) {
+      if (prop.type !== "Property" || prop.computed) return;
+      const key =
+        prop.key.type === "Identifier"
+          ? prop.key.name
+          : prop.key.type === "Literal"
+            ? prop.key.value
+            : null;
+      if (!isColorProperty(key)) return;
+      const v = prop.value;
+      if (v.type === "Literal" && typeof v.value === "string") {
+        if (hasColorSyntax(v.value) || isNamedColorValue(v.value)) {
+          reportColorValue(v, v.value);
+        }
+      } else if (v.type === "TemplateLiteral") {
+        for (const q of v.quasis) {
+          if (hasColorSyntax(q.value.cooked ?? q.value.raw)) {
+            reportColorValue(v, context.sourceCode.getText(v));
+            break;
+          }
+        }
+      }
+    }
+
+    // className analysis: string literal or template literal.
+    function checkClassName(node) {
+      if (node.type === "Literal" && typeof node.value === "string") {
+        const bad = findArbitraryColor(node.value, ramps);
+        if (bad !== null) {
+          context.report({
+            node,
+            messageId: "arbitraryColor",
+            data: { value: bad.slice(0, 40) },
+          });
+        }
+      } else if (node.type === "TemplateLiteral") {
+        // Interpolation inside a [...] arbitrary value is JIT-invisible.
+        if (interpolationInsideArbitrary(node)) {
+          context.report({
+            node,
+            messageId: "arbitraryInterpolation",
+            data: { value: context.sourceCode.getText(node).slice(0, 40) },
+          });
+          return;
+        }
+        // Static quasis can still contain bg-[#...] literally.
+        for (const q of node.quasis) {
+          const bad = findArbitraryColor(q.value.cooked ?? q.value.raw, ramps);
+          if (bad !== null) {
+            context.report({
+              node,
+              messageId: "arbitraryColor",
+              data: { value: bad.slice(0, 40) },
+            });
+            break;
+          }
+        }
+      }
+    }
+
+    // True when any `${...}` expression sits inside an unclosed `[` of a
+    // Tailwind arbitrary value (e.g. `bg-[${x}]`).
+    function interpolationInsideArbitrary(tpl) {
+      for (let i = 0; i < tpl.expressions.length; i++) {
+        const before = tpl.quasis[i].value.cooked ?? tpl.quasis[i].value.raw;
+        const lastOpen = before.lastIndexOf("[");
+        const lastClose = before.lastIndexOf("]");
+        if (lastOpen > lastClose) return true;
+      }
+      return false;
+    }
+
+    return {
+      // Inline style objects, both JSX and plain.
+      ObjectExpression(node) {
+        for (const prop of node.properties) checkStyleProperty(prop);
+      },
+
+      JSXAttribute(node) {
+        const name = node.name && node.name.name;
+        if (!isClassNameAttr(name)) return;
+        const val = node.value;
+        if (!val) return;
+        if (val.type === "Literal") checkClassName(val);
+        else if (
+          val.type === "JSXExpressionContainer" &&
+          (val.expression.type === "Literal" ||
+            val.expression.type === "TemplateLiteral")
+        ) {
+          checkClassName(val.expression);
+        }
+      },
+
+      TaggedTemplateExpression(node) {
+        if (!isCssTag(node.tag)) return;
+        for (const q of node.quasi.quasis) {
+          const text = q.value.cooked ?? q.value.raw;
+          if (hasColorSyntax(text)) {
+            reportColorValue(node.quasi, text.trim().slice(0, 40));
+            break;
+          }
+        }
+      },
+
+      // Bare raw-ramp string references, e.g. "gray.500".
+      Literal(node) {
+        if (typeof node.value !== "string") return;
+        const ramp = matchRampRef(node.value, ramps);
+        if (ramp) {
+          context.report({
+            node,
+            messageId: "rawRamp",
+            data: { value: node.value, ramp },
+          });
+        }
+      },
+    };
+  },
+};

package/rules/no-raw-fetch.js

@@ -0,0 +1,100 @@
+// stapel/no-raw-fetch — frontend-guardrails §2.2 (failure mode F2).
+// Network access goes through the codegen client only. Raw fetch/axios/ky/
+// XMLHttpRequest bypasses typing, the error envelope, and auth/CSRF handling.
+// The recommended preset turns this OFF for the api layer of a pair (the client
+// itself is the one legal home of fetch) via file overrides.
+import { stapelSettings } from "../lib/data.js";
+
+const HINT =
+  "Requests go through the codegen client only: const api = createAuthApi(client); await api.me(). Operations: <pkg>/manifest.json §operations.";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow raw fetch/axios/ky/XMLHttpRequest outside the codegen API layer.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          modules: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      rawFetch: "Direct {{what}}(). " + HINT,
+      rawXhr: "Direct `new XMLHttpRequest()`. " + HINT,
+      rawImport: 'Import of HTTP client "{{source}}". ' + HINT,
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const extraModules = context.options[0]?.modules ?? [];
+    const bannedModules = new Set([
+      "axios",
+      "ky",
+      "got",
+      "superagent",
+      ...(settings.httpModules ?? []),
+      ...extraModules,
+    ]);
+
+    function reportFetch(node, what) {
+      context.report({ node, messageId: "rawFetch", data: { what } });
+    }
+
+    return {
+      // fetch(...), globalThis.fetch(...), window.fetch(...), self.fetch(...)
+      CallExpression(node) {
+        const callee = node.callee;
+        if (callee.type === "Identifier" && callee.name === "fetch") {
+          reportFetch(node, "fetch");
+          return;
+        }
+        if (
+          callee.type === "MemberExpression" &&
+          !callee.computed &&
+          callee.property.type === "Identifier" &&
+          callee.property.name === "fetch" &&
+          callee.object.type === "Identifier" &&
+          ["globalThis", "window", "self"].includes(callee.object.name)
+        ) {
+          reportFetch(node, `${callee.object.name}.fetch`);
+        }
+        // axios(...) / axios.get(...) / ky(...) — call on a banned identifier
+        const root =
+          callee.type === "Identifier"
+            ? callee
+            : callee.type === "MemberExpression" &&
+                callee.object.type === "Identifier"
+              ? callee.object
+              : null;
+        if (root && bannedModules.has(root.name)) {
+          reportFetch(node, root.name);
+        }
+      },
+
+      NewExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "XMLHttpRequest"
+        ) {
+          context.report({ node, messageId: "rawXhr" });
+        }
+      },
+
+      ImportDeclaration(node) {
+        if (bannedModules.has(node.source.value)) {
+          context.report({
+            node,
+            messageId: "rawImport",
+            data: { source: node.source.value },
+          });
+        }
+      },
+    };
+  },
+};

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

@@ -0,0 +1,65 @@
+// stapel/no-raw-token-import — frontend-guardrails §2.2.
+// `@stapel/tokens/raw` is the ONLY legal door to the L1 ramps, and only the
+// theme-config + the showcase may open it. Everywhere else raw ramps must not
+// be reachable (components reference tokens, not hex). The recommended preset
+// turns this rule OFF for theme-config/showcase/scripts via file overrides
+// (§2.2: "overrides-исключения"); the rule itself always flags.
+import { stapelSettings } from "../lib/data.js";
+
+const RAW = "@stapel/tokens/raw";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing @stapel/tokens/raw outside theme-config and the showcase.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: { modules: { type: "array", items: { type: "string" } } },
+        additionalProperties: false,
+      },
+    ],
+    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.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const extra = context.options[0]?.modules ?? [];
+    const banned = new Set([RAW, ...(settings.rawModules ?? []), ...extra]);
+
+    function check(node, source) {
+      if (typeof source === "string" && banned.has(source)) {
+        context.report({ node, messageId: "rawImport", data: { source } });
+      }
+    }
+
+    return {
+      ImportDeclaration(node) {
+        check(node, node.source.value);
+      },
+      ExportNamedDeclaration(node) {
+        if (node.source) check(node, node.source.value);
+      },
+      ExportAllDeclaration(node) {
+        if (node.source) check(node, node.source.value);
+      },
+      ImportExpression(node) {
+        if (node.source.type === "Literal") check(node, node.source.value);
+      },
+      CallExpression(node) {
+        if (
+          node.callee.type === "Identifier" &&
+          node.callee.name === "require" &&
+          node.arguments[0]?.type === "Literal"
+        ) {
+          check(node, node.arguments[0].value);
+        }
+      },
+    };
+  },
+};