@stapel/eslint-plugin 0.2.0

package/rules/demo-literal-meta.js

@@ -0,0 +1,124 @@
+// stapel/demo-literal-meta — frontend-guardrails §4.2. defineDemo() must be
+// called with a LITERAL object so the static extractor (gen:demos, AST) can
+// project it into demos.json / manifest.demos / CSF stories and evaluate the
+// completeness gate. A dynamic definition is not "wrong" at runtime; it is
+// INVISIBLE to those projections, so the demo silently vanishes from the
+// catalog, the viewer, and the gate. This rule keeps the meta extractable: the
+// argument is an object literal; `id`/`title`/`description` are string
+// literals; `component` is a plain reference (identifier or member); and
+// `variants` is an object literal with static keys. `render` closures and other
+// values are intentionally free — only the statically-read meta is constrained.
+const CATALOG =
+  "gen:demos extracts demos.json/manifest.demos/CSF from these literals — keep the meta static or the demo never reaches the catalog, the viewer, or the completeness gate.";
+
+const DEFINERS = new Set(["defineDemo"]);
+
+function isStringLiteral(node) {
+  return node && node.type === "Literal" && typeof node.value === "string";
+}
+
+function objProp(objExpr, key) {
+  for (const p of objExpr.properties) {
+    if (
+      p.type === "Property" &&
+      !p.computed &&
+      ((p.key.type === "Identifier" && p.key.name === key) ||
+        (p.key.type === "Literal" && p.key.value === key))
+    )
+      return p;
+  }
+  return null;
+}
+
+function isReference(node) {
+  return (
+    node &&
+    (node.type === "Identifier" ||
+      (node.type === "MemberExpression" && !node.computed))
+  );
+}
+
+function isDefiner(callee) {
+  if (callee.type === "Identifier") return DEFINERS.has(callee.name);
+  if (
+    callee.type === "MemberExpression" &&
+    !callee.computed &&
+    callee.property.type === "Identifier"
+  )
+    return DEFINERS.has(callee.property.name);
+  return false;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require defineDemo() to be called with a literal object (literal id/title/description, a component reference, an object-literal variants map) so the demo registry stays statically extractable.",
+    },
+    schema: [],
+    messages: {
+      notObject:
+        "defineDemo() needs a literal object argument, got a dynamic value. " +
+        CATALOG +
+        " §4.2 stapel/demo-literal-meta",
+      dynamicString:
+        'defineDemo `{{key}}` must be a string literal — it is the catalog/viewer copy. ' +
+        CATALOG +
+        " §4.2 stapel/demo-literal-meta",
+      dynamicComponent:
+        "defineDemo `component` must be a component reference (e.g. `PasswordlessLogin`) so the completeness gate can read its name. " +
+        CATALOG +
+        " §4.2 stapel/demo-literal-meta",
+      dynamicVariants:
+        "defineDemo `variants` must be an object literal with static keys — each key becomes a viewer story and a smoke test. " +
+        CATALOG +
+        " §4.2 stapel/demo-literal-meta",
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isDefiner(node.callee)) return;
+        const arg = node.arguments[0];
+        if (!arg || arg.type !== "ObjectExpression") {
+          context.report({ node: arg ?? node, messageId: "notObject" });
+          return;
+        }
+
+        for (const key of ["id", "title", "description"]) {
+          const p = objProp(arg, key);
+          if (p && !isStringLiteral(p.value)) {
+            context.report({
+              node: p.value,
+              messageId: "dynamicString",
+              data: { key },
+            });
+          }
+        }
+
+        const componentProp = objProp(arg, "component");
+        if (componentProp && !isReference(componentProp.value)) {
+          context.report({
+            node: componentProp.value,
+            messageId: "dynamicComponent",
+          });
+        }
+
+        const variantsProp = objProp(arg, "variants");
+        if (variantsProp) {
+          const v = variantsProp.value;
+          if (v.type !== "ObjectExpression") {
+            context.report({ node: v, messageId: "dynamicVariants" });
+          } else {
+            for (const p of v.properties) {
+              if (p.type !== "Property" || p.computed) {
+                context.report({ node: p, messageId: "dynamicVariants" });
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/rules/event-literal-meta.js

@@ -0,0 +1,154 @@
+// stapel/event-literal-meta — frontend-guardrails §3.1. defineEvent() must be
+// called with a LITERAL object so the static extractor (gen:events, ts-morph/
+// AST) can project it into events.json — the single source the lint (G4) and
+// the report (G5) read. A dynamic definition is not "wrong" at runtime; it is
+// INVISIBLE to the registry and reports, so the whole typed-analytics layer
+// silently loses that event. This rule keeps definitions statically
+// extractable: the argument is an object literal, `name`/`description` are
+// string literals, and every prop is built with a prop.* builder.
+import { stapelSettings } from "../lib/data.js";
+
+const DEFAULT_DEFINERS = ["defineEvent"];
+const DEFAULT_PROP_BUILDER = "prop"; // prop.string/number/boolean/oneOf
+
+const CATALOG =
+  "gen:events extracts events.json from these literals — keep it static or the event never reaches the registry/reports.";
+
+function isStringLiteral(node) {
+  return node && node.type === "Literal" && typeof node.value === "string";
+}
+
+function objProp(objExpr, key) {
+  for (const p of objExpr.properties) {
+    if (
+      p.type === "Property" &&
+      !p.computed &&
+      ((p.key.type === "Identifier" && p.key.name === key) ||
+        (p.key.type === "Literal" && p.key.value === key))
+    )
+      return p;
+  }
+  return null;
+}
+
+/** True if `node` is a `prop.<builder>(...)` call. */
+function isPropBuilderCall(node, builderName) {
+  return (
+    node &&
+    node.type === "CallExpression" &&
+    node.callee.type === "MemberExpression" &&
+    !node.callee.computed &&
+    node.callee.object.type === "Identifier" &&
+    node.callee.object.name === builderName &&
+    node.callee.property.type === "Identifier"
+  );
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require defineEvent() to be called with a literal object (literal name/description, prop.* builders) so the event registry stays statically extractable.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          definers: { type: "array", items: { type: "string" } },
+          propBuilder: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      notObject:
+        "defineEvent() needs a literal object argument, got a dynamic value. " +
+        CATALOG +
+        " §3.1 stapel/event-literal-meta",
+      dynamicName:
+        'defineEvent `name` must be a string literal (e.g. "pricing.plan.selected"), not a computed value. ' +
+        CATALOG +
+        " §3.1 stapel/event-literal-meta",
+      missingDescription:
+        "defineEvent `description` must be a string literal — it is the registry/report copy for this event. " +
+        CATALOG +
+        " §3.1 stapel/event-literal-meta",
+      dynamicProps:
+        "defineEvent `props` must be a literal object of prop.* builders. " +
+        CATALOG +
+        " §3.1 stapel/event-literal-meta",
+      dynamicProp:
+        'defineEvent prop "{{prop}}" must use a prop.* builder (e.g. prop.oneOf(["a","b"], "…")), not a dynamic value — otherwise the extractor cannot read its meta. ' +
+        CATALOG +
+        " §3.1 stapel/event-literal-meta",
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const definers = new Set(
+      context.options[0]?.definers ?? settings.eventDefiners ?? DEFAULT_DEFINERS
+    );
+    const builder = context.options[0]?.propBuilder ?? DEFAULT_PROP_BUILDER;
+
+    function isDefiner(callee) {
+      if (callee.type === "Identifier") return definers.has(callee.name);
+      if (
+        callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier"
+      )
+        return definers.has(callee.property.name);
+      return false;
+    }
+
+    return {
+      CallExpression(node) {
+        if (!isDefiner(node.callee)) return;
+        const arg = node.arguments[0];
+        if (!arg || arg.type !== "ObjectExpression") {
+          context.report({ node: arg ?? node, messageId: "notObject" });
+          return;
+        }
+
+        const nameProp = objProp(arg, "name");
+        if (nameProp && !isStringLiteral(nameProp.value)) {
+          context.report({ node: nameProp.value, messageId: "dynamicName" });
+        }
+
+        const descProp = objProp(arg, "description");
+        if (descProp && !isStringLiteral(descProp.value)) {
+          context.report({ node: descProp.value, messageId: "missingDescription" });
+        }
+
+        const propsProp = objProp(arg, "props");
+        if (propsProp) {
+          const propsVal = propsProp.value;
+          if (propsVal.type !== "ObjectExpression") {
+            context.report({ node: propsVal, messageId: "dynamicProps" });
+          } else {
+            for (const p of propsVal.properties) {
+              if (p.type !== "Property" || p.computed) {
+                context.report({ node: p, messageId: "dynamicProps" });
+                continue;
+              }
+              if (!isPropBuilderCall(p.value, builder)) {
+                const key =
+                  p.key.type === "Identifier"
+                    ? p.key.name
+                    : p.key.type === "Literal"
+                      ? String(p.key.value)
+                      : "?";
+                context.report({
+                  node: p.value,
+                  messageId: "dynamicProp",
+                  data: { prop: key },
+                });
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/rules/i18n-key-exists.js

@@ -0,0 +1,77 @@
+// stapel/i18n-key-exists — frontend-guardrails §2.2.
+// A `t("...")` key must exist in the generated i18n registry (pair manifests +
+// app keys). Data-driven: the key set comes from the manifests the codegen
+// writes. False-positive policy (§2.2): only string-literal keys are checked,
+// and only within a MANAGED namespace (a top-level segment some manifest owns)
+// — an unknown key under an unmanaged namespace is assumed app-local, not a
+// typo, so bespoke host keys never false-positive.
+import { loadI18nRegistry, stapelSettings } from "../lib/data.js";
+
+const DEFAULT_CALLEES = ["t", "translate"];
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow translation keys that are absent from the generated i18n registry.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          functionNames: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      unknownKey:
+        'Unknown i18n key "{{key}}". It is not in the generated registry for the "{{ns}}" namespace. Add it to the owning package\'s keys (e.g. i18n/keys.ts) or fix the typo. Convention: @stapel/core/llms.txt §i18n.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const registry = loadI18nRegistry(settings);
+    if (!registry.loaded) return {}; // no catalog → no-op, never guess
+
+    const names = new Set(
+      context.options[0]?.functionNames ??
+        settings.i18nFunctions ??
+        DEFAULT_CALLEES
+    );
+
+    function keyArg(node) {
+      const first = node.arguments[0];
+      if (first && first.type === "Literal" && typeof first.value === "string")
+        return first;
+      return null;
+    }
+
+    function isTranslator(callee) {
+      if (callee.type === "Identifier") return names.has(callee.name);
+      // obj.t("...") — e.g. i18n.t, useT()-returned `t` is usually a bare id,
+      // but support member form for `.t`/`.translate`.
+      if (
+        callee.type === "MemberExpression" &&
+        !callee.computed &&
+        callee.property.type === "Identifier"
+      )
+        return names.has(callee.property.name);
+      return false;
+    }
+
+    return {
+      CallExpression(node) {
+        if (!isTranslator(node.callee)) return;
+        const arg = keyArg(node);
+        if (!arg) return; // dynamic key → skip (FP policy)
+        const key = arg.value;
+        if (!registry.manages(key)) return; // unmanaged namespace → app-local
+        if (registry.has(key)) return;
+        const ns = key.slice(0, key.indexOf("."));
+        context.report({ node: arg, messageId: "unknownKey", data: { key, ns } });
+      },
+    };
+  },
+};

package/rules/known-event.js

@@ -0,0 +1,133 @@
+// stapel/known-event — frontend-guardrails §3 (failure mode F10: "string events
+// with invented names"). A track()/tracked()/trackedSubmit() call whose event
+// is not in the generated events.json is flagged as DRIFT — a warning, because
+// it is legitimately transient: right after you add a defineEvent (or a flow),
+// the registry is stale until `pnpm gen:events` runs. The message says so. Once
+// the drift gate is green, an unknown name is a typo or a deleted event.
+//
+// Data-driven (§2.1): the known set is the `events` section of the package
+// manifests — the same projection the report (G5) reads. A missing catalog
+// degrades the rule to a no-op (never guesses). Resolution is conservative:
+// a string-literal event name, or an in-file identifier that resolves to a
+// defineEvent({ name: "…" }) — anything else is skipped, so this rule never
+// false-positives on an event it cannot statically read.
+import { loadEventsCatalog, stapelSettings } from "../lib/data.js";
+
+const DEFAULT_EMITTERS = ["track", "tracked", "trackedSubmit"];
+const DEFAULT_DEFINERS = ["defineEvent"];
+
+function isStringLiteral(node) {
+  return node && node.type === "Literal" && typeof node.value === "string";
+}
+
+function objProp(objExpr, key) {
+  for (const p of objExpr.properties) {
+    if (
+      p.type === "Property" &&
+      !p.computed &&
+      ((p.key.type === "Identifier" && p.key.name === key) ||
+        (p.key.type === "Literal" && p.key.value === key))
+    )
+      return p;
+  }
+  return null;
+}
+
+function calleeName(callee) {
+  if (callee.type === "Identifier") return callee.name;
+  if (
+    callee.type === "MemberExpression" &&
+    !callee.computed &&
+    callee.property.type === "Identifier"
+  )
+    return callee.property.name;
+  return null;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Warn when a tracked event name is absent from the generated events.json (registry drift — run gen:events).",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          emitters: { type: "array", items: { type: "string" } },
+          definers: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      unknownEvent:
+        'Event "{{name}}" is not in the generated events.json. If you just declared it, run `pnpm gen:events` to refresh the registry; otherwise it is a typo or a removed event. §3 stapel/known-event',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const catalog = loadEventsCatalog(settings);
+    if (!catalog.loaded) return {}; // no catalog → no-op, never guess
+
+    const emitters = new Set(
+      context.options[0]?.emitters ?? settings.eventEmitters ?? DEFAULT_EMITTERS
+    );
+    const definers = new Set(
+      context.options[0]?.definers ?? settings.eventDefiners ?? DEFAULT_DEFINERS
+    );
+
+    // identifier → event name, filled from `const X = defineEvent({name})`.
+    const localEvents = new Map();
+    // Deferred checks — declarations may follow first use in source order.
+    const pending = [];
+
+    function definerName(callee) {
+      const n = calleeName(callee);
+      return n && definers.has(n);
+    }
+
+    return {
+      VariableDeclarator(node) {
+        if (
+          node.id.type === "Identifier" &&
+          node.init &&
+          node.init.type === "CallExpression" &&
+          definerName(node.init.callee)
+        ) {
+          const arg = node.init.arguments[0];
+          if (arg && arg.type === "ObjectExpression") {
+            const nameProp = objProp(arg, "name");
+            if (nameProp && isStringLiteral(nameProp.value)) {
+              localEvents.set(node.id.name, nameProp.value.value);
+            }
+          }
+        }
+      },
+
+      CallExpression(node) {
+        const name = calleeName(node.callee);
+        if (!name || !emitters.has(name)) return;
+        const evArg = node.arguments[0];
+        if (!evArg) return;
+        if (isStringLiteral(evArg)) {
+          pending.push({ node: evArg, name: evArg.value });
+        } else if (evArg.type === "Identifier") {
+          pending.push({ node: evArg, ident: evArg.name });
+        }
+        // member/other event expressions → not statically resolvable → skip.
+      },
+
+      "Program:exit"() {
+        for (const p of pending) {
+          const name = p.name ?? localEvents.get(p.ident);
+          if (name == null) continue; // unresolved identifier → skip
+          if (!catalog.isKnown(name)) {
+            context.report({ node: p.node, messageId: "unknownEvent", data: { name } });
+          }
+        }
+      },
+    };
+  },
+};

package/rules/no-direct-analytics-provider.js

@@ -0,0 +1,102 @@
+// stapel/no-direct-analytics-provider — frontend-guardrails §2.2 / §3.
+// Analytics goes through the @stapel/core facade (consent gate, PII guard,
+// offline queue, fan-out), NEVER straight into a vendor SDK. Importing a
+// provider package anywhere but the facade's provider-adapter module bypasses
+// consent and PII enforcement in one line — the cheapest F9 violation there
+// is. The recommended preset turns this rule OFF for `analytics/providers.*`
+// (the one legal adapter home) via file overrides; the rule itself always
+// flags.
+//
+// Vendor list: known analytics SDK package prefixes. Extendable per host via
+// options ({ providers: ["@acme/tracker"] }) or settings.stapel.providerModules.
+import { stapelSettings } from "../lib/data.js";
+
+const DEFAULT_PROVIDERS = [
+  "posthog-js",
+  "posthog-node",
+  "mixpanel-browser",
+  "mixpanel",
+  "amplitude-js",
+  "@amplitude/",
+  "@segment/",
+  "analytics-node",
+  "@rudderstack/",
+  "rudder-sdk-js",
+  "@snowplow/",
+  "react-ga",
+  "react-ga4",
+  "@google-analytics/",
+  "@datadog/browser-rum",
+  "@fullstory/",
+  "heap-api",
+];
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing analytics provider SDKs outside the core facade's provider adapters.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          providers: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      directProvider:
+        'Direct analytics provider import "{{source}}". Emit through the @stapel/core facade instead — analytics.track(event, props) / tracked(event, props, handler) — which owns consent, PII guarding, and the offline queue (§3). Provider SDKs are wired ONCE, in the facade\'s provider adapter (analytics/providers.ts). See @stapel/core/llms.txt §analytics.',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const extra = context.options[0]?.providers ?? [];
+    const prefixes = [
+      ...DEFAULT_PROVIDERS,
+      ...(settings.providerModules ?? []),
+      ...extra,
+    ];
+
+    function isProvider(source) {
+      return prefixes.some((p) =>
+        p.endsWith("/") || p.endsWith("-")
+          ? source.startsWith(p)
+          : source === p || source.startsWith(`${p}/`)
+      );
+    }
+
+    function check(node, source) {
+      if (typeof source === "string" && isProvider(source)) {
+        context.report({ node, messageId: "directProvider", 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);
+        }
+      },
+    };
+  },
+};