@stapel/eslint-plugin 0.2.0

package/lib/data.js

@@ -0,0 +1,349 @@
+// Data layer for the guardrail rules (frontend-guardrails §2.1: "Data-driven,
+// out of the SAME artifacts"). Rules never carry their own token / i18n lists —
+// they read the generated manifests the codegen writes, so lint and code cannot
+// drift. Everything here is defensive: a missing manifest degrades a rule to a
+// no-op (empty catalog) rather than crashing the lint run, and every lookup is
+// overridable via `settings.stapel` so consumers (and RuleTester) stay
+// deterministic.
+import { createRequire } from "node:module";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Walk up from `start` until a directory contains `marker`; null if none. */
+function findUp(marker, start) {
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, marker))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Nearest pnpm/monorepo workspace root above `from`. */
+function workspaceRoot(from) {
+  return (
+    findUp("pnpm-workspace.yaml", from) ??
+    findUp("pnpm-lock.yaml", from) ??
+    null
+  );
+}
+
+// ── Token catalog ──────────────────────────────────────────────────────────
+
+function loadTokensManifest(settings) {
+  if (settings.tokensManifest) return settings.tokensManifest;
+  if (settings.tokensManifestPath) return readJson(settings.tokensManifestPath);
+  // The token authority is @stapel/tokens — a real dependency of this plugin.
+  try {
+    return require("@stapel/tokens/manifest.json");
+  } catch {
+    /* fall through to workspace discovery */
+  }
+  const root = workspaceRoot(HERE);
+  if (root) {
+    const m = readJson(join(root, "packages", "tokens", "manifest.json"));
+    if (m) return m;
+  }
+  return null;
+}
+
+function buildTokenCatalog(manifest) {
+  const t = manifest?.tokens ?? {};
+  const core = new Set(t.core ?? []);
+  const component = new Set(t.component ?? []);
+  const ramps = new Set(manifest?.ramps?.names ?? []);
+  const all = new Set([...core, ...component]);
+  return {
+    core,
+    component,
+    ramps,
+    all,
+    /** true if `name` is a known L2 core or L3 component token */
+    hasToken: (name) => all.has(name),
+    /** true if `name` is a known L1 raw ramp (e.g. "gray", "brand") */
+    hasRamp: (name) => ramps.has(name),
+    loaded: all.size > 0 || ramps.size > 0,
+  };
+}
+
+let _tokenCatalogDefault;
+export function loadTokenCatalog(settings = {}) {
+  const overridden =
+    settings.tokensManifest || settings.tokensManifestPath;
+  if (overridden) return buildTokenCatalog(loadTokensManifest(settings));
+  if (!_tokenCatalogDefault) {
+    _tokenCatalogDefault = buildTokenCatalog(loadTokensManifest(settings));
+  }
+  return _tokenCatalogDefault;
+}
+
+// ── i18n key registry ────────────────────────────────────────────────────────
+
+function discoverWorkspaceI18nKeys(from) {
+  const root = workspaceRoot(from);
+  if (!root) return [];
+  const pkgsDir = join(root, "packages");
+  if (!existsSync(pkgsDir)) return [];
+  const out = [];
+  let entries = [];
+  try {
+    entries = readdirSync(pkgsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  for (const name of entries) {
+    const manifest = readJson(join(pkgsDir, name, "manifest.json"));
+    if (manifest && Array.isArray(manifest.i18nKeys)) {
+      out.push(manifest);
+    }
+  }
+  return out;
+}
+
+function buildI18nRegistry(manifests, extraKeys) {
+  const keys = new Set(extraKeys ?? []);
+  for (const m of manifests) {
+    for (const k of m.i18nKeys ?? []) keys.add(k);
+  }
+  // Managed namespaces = the top-level segment of every known key. The
+  // existence rule only fires inside a MANAGED namespace (false-positive
+  // policy, §2.2): an unknown key under a namespace nobody manages is treated
+  // as an app-local key, not a typo.
+  const namespaces = new Set();
+  for (const k of keys) {
+    const dot = k.indexOf(".");
+    if (dot > 0) namespaces.add(k.slice(0, dot));
+  }
+  return {
+    keys,
+    namespaces,
+    has: (k) => keys.has(k),
+    manages: (k) => {
+      const dot = k.indexOf(".");
+      return dot > 0 && namespaces.has(k.slice(0, dot));
+    },
+    loaded: keys.size > 0,
+  };
+}
+
+let _i18nDefault;
+export function loadI18nRegistry(settings = {}) {
+  if (settings.i18nKeys) {
+    return buildI18nRegistry([], settings.i18nKeys);
+  }
+  if (settings.i18nManifests) {
+    return buildI18nRegistry(settings.i18nManifests, settings.extraI18nKeys);
+  }
+  if (!_i18nDefault) {
+    _i18nDefault = buildI18nRegistry(
+      discoverWorkspaceI18nKeys(process.cwd ? process.cwd() : HERE),
+      undefined
+    );
+  }
+  return _i18nDefault;
+}
+
+// ── analytics event registry (events.json / manifest.events) ─────────────────
+//
+// The known-event lint (G4) reads the SAME generated projection the report (G5)
+// reads: the `events` section of each package manifest.json (defineEvent call
+// sites → `defined`, flows.json funnels → `flows`). A missing manifest / events
+// section degrades the rule to a no-op (empty catalog), never a crash — exactly
+// like the token and i18n loaders above (§2.1: one source, all projections).
+
+function discoverWorkspaceEventManifests(from) {
+  const root = workspaceRoot(from);
+  if (!root) return [];
+  const pkgsDir = join(root, "packages");
+  if (!existsSync(pkgsDir)) return [];
+  const out = [];
+  let entries = [];
+  try {
+    entries = readdirSync(pkgsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  for (const name of entries) {
+    const manifest = readJson(join(pkgsDir, name, "manifest.json"));
+    if (manifest && manifest.events) out.push(manifest);
+  }
+  return out;
+}
+
+/** Strip the `<step>` / `*` placeholder tail off a flow event pattern. */
+function flowBaseOf(eventPattern) {
+  return String(eventPattern)
+    .replace(/\.<step>$/, "")
+    .replace(/\.\*$/, "");
+}
+
+function buildEventsCatalog(manifests, extraNames) {
+  const defined = new Set(extraNames ?? []);
+  const flowBases = new Set();
+  for (const m of manifests) {
+    const ev = m.events;
+    if (!ev) continue;
+    for (const d of ev.defined ?? []) if (d && d.name) defined.add(d.name);
+    for (const f of ev.flows ?? []) {
+      if (f && f.event) flowBases.add(flowBaseOf(f.event));
+      if (f && f.flow) flowBases.add(`flow.${f.flow}`);
+    }
+  }
+  return {
+    defined,
+    flowBases,
+    /**
+     * A name is known if it is a declared event, OR it is a flow event under a
+     * known funnel base (`flow.<id>.<step>`) — flow steps are open-ended, so we
+     * match by prefix rather than enumerating every step.
+     */
+    isKnown: (name) => {
+      if (defined.has(name)) return true;
+      for (const base of flowBases) {
+        if (name === base || name.startsWith(base + ".")) return true;
+      }
+      return false;
+    },
+    loaded: defined.size > 0 || flowBases.size > 0,
+  };
+}
+
+let _eventsCatalogDefault;
+export function loadEventsCatalog(settings = {}) {
+  if (settings.eventNames) {
+    return buildEventsCatalog([], settings.eventNames);
+  }
+  if (settings.eventsManifests) {
+    return buildEventsCatalog(settings.eventsManifests, settings.extraEventNames);
+  }
+  if (!_eventsCatalogDefault) {
+    _eventsCatalogDefault = buildEventsCatalog(
+      discoverWorkspaceEventManifests(process.cwd ? process.cwd() : HERE),
+      undefined
+    );
+  }
+  return _eventsCatalogDefault;
+}
+
+// ── operation-path catalog (manifest.operations) ─────────────────────────────
+//
+// The no-string-paths lint reads the SAME generated projection the code and the
+// llms.txt read: the `operations` section of each package manifest.json (schema
+// operationId → { method, path }). A path an agent hand-writes is authoritative
+// only if it matches a catalogued operation — so the rule can name the op to
+// call instead. A missing manifest / operations section degrades the data to an
+// empty catalog (the rule still flags the syntactic `client.<verb>("/…")` shape,
+// never crashes) — exactly like the token / i18n / events loaders above (§2.1).
+
+function discoverWorkspaceOperationManifests(from) {
+  const root = workspaceRoot(from);
+  if (!root) return [];
+  const pkgsDir = join(root, "packages");
+  if (!existsSync(pkgsDir)) return [];
+  const out = [];
+  let entries = [];
+  try {
+    entries = readdirSync(pkgsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  for (const name of entries) {
+    const manifest = readJson(join(pkgsDir, name, "manifest.json"));
+    if (manifest && manifest.operations) out.push(manifest);
+  }
+  return out;
+}
+
+function buildOperationCatalog(manifests, extraPaths) {
+  // path → { pkg, operation } for the exact-match lookup + a set of paths for
+  // template-prefix matching (`\`${base}/me/\`` shares the trailing segments).
+  const byPath = new Map();
+  for (const p of extraPaths ?? []) if (p) byPath.set(p, { pkg: null, operation: null });
+  for (const m of manifests) {
+    const pkg = m.package ?? null;
+    for (const [id, op] of Object.entries(m.operations ?? {})) {
+      if (op && typeof op.path === "string" && !byPath.has(op.path)) {
+        byPath.set(op.path, { pkg, operation: id });
+      }
+    }
+  }
+  const paths = [...byPath.keys()];
+  /**
+   * The catalogued operation for a path string, by exact match or — for a
+   * client-relative literal like `/me/` under a `/auth/api` base URL — by
+   * trailing-segment suffix. Returns { pkg, operation } or null.
+   */
+  const resolve = (str) => {
+    // A meaningful path has a segment beyond the leading slash — never resolve a
+    // bare "/" (every catalogued path ends with one, so it would match all).
+    if (typeof str !== "string" || str.length < 2 || !/[A-Za-z0-9]/.test(str)) {
+      return null;
+    }
+    const exact = byPath.get(str);
+    if (exact) return exact;
+    // Suffix match aligns at a segment boundary because `str` starts with "/".
+    for (const p of paths) if (str.startsWith("/") && p.endsWith(str)) return byPath.get(p);
+    return null;
+  };
+  return {
+    byPath,
+    paths,
+    resolve,
+    /** Exact catalogued operation for a literal path string, else null. */
+    lookup: (str) => byPath.get(str) ?? null,
+    /** True if `str` is (or ends with) a catalogued operation path. */
+    matches: (str) => resolve(str) !== null,
+    loaded: byPath.size > 0,
+  };
+}
+
+let _operationCatalogDefault;
+export function loadOperationCatalog(settings = {}) {
+  if (settings.operationPaths) {
+    return buildOperationCatalog([], settings.operationPaths);
+  }
+  if (settings.operationsManifests) {
+    return buildOperationCatalog(settings.operationsManifests, settings.extraOperationPaths);
+  }
+  if (!_operationCatalogDefault) {
+    _operationCatalogDefault = buildOperationCatalog(
+      discoverWorkspaceOperationManifests(process.cwd ? process.cwd() : HERE),
+      undefined
+    );
+  }
+  return _operationCatalogDefault;
+}
+
+/** Read `context.settings.stapel` (flat config) with a stable empty default. */
+export function stapelSettings(context) {
+  return (context.settings && context.settings.stapel) || {};
+}
+
+// Test hook: clear memoized defaults so RuleTester cases stay independent.
+export function __resetCaches() {
+  _tokenCatalogDefault = undefined;
+  _i18nDefault = undefined;
+  _eventsCatalogDefault = undefined;
+  _operationCatalogDefault = undefined;
+}
+
+export { resolve as _resolve };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@stapel/eslint-plugin",
+  "version": "0.2.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": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/eslint-plugin"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./stylelint": "./stylelint/index.js",
+    "./stylelint/preset": "./stylelint/preset.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "rules",
+    "stylelint",
+    "README.md"
+  ],
+  "dependencies": {
+    "@stapel/tokens": "^0.2.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9",
+    "stylelint": ">=16"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "^8.35.0",
+    "eslint": "^9.30.0",
+    "stylelint": "^16.0.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}

package/rules/clickable-needs-event.js

@@ -0,0 +1,194 @@
+// stapel/clickable-needs-event — frontend-guardrails §3.2 (failure mode F10:
+// "analytics as an afterthought — the agent generates clickable UI with no
+// events"). A JSX element carrying an interactive handler (onClick/onSubmit/
+// onPointerDown/…) must statically fall into exactly ONE of three outcomes:
+//
+//   (a) the handler is wrapped — onClick={tracked(event, props, handler)} (or
+//       trackedSubmit(...)); the wrapper name is the static marker.
+//   (b) the click steps a flow machine — the element is marked
+//       data-analytics="flow"; the machine is already auto-instrumented
+//       (flow.<id>.<step>), so the funnel emits itself.
+//   (c) the click is deliberately untracked — data-analytics="none" plus a
+//       NON-EMPTY data-analytics-reason="…"; the report (G5) lists it under
+//       "explicitly untracked".
+//
+// Everything is checked syntactically (§3.2: "syntactic checkability >
+// semantic undecidability"). The check is per-element, not per-attribute — one
+// outcome covers all of an element's handlers.
+//
+// Decorative/technical clicks are EXEMPT by policy (documented here so the
+// message can teach it): a handler whose body does nothing but call
+// e.stopPropagation() / e.preventDefault() is plumbing, not a user action — it
+// does not represent an interaction to track. Everything else that carries an
+// interactive prop (including custom components that merely forward onClick)
+// must pick an outcome; a forwarding component marks itself
+// data-analytics="none" reason="passthrough" and the real click point is
+// tracked downstream.
+import { stapelSettings } from "../lib/data.js";
+
+const DEFAULT_HANDLERS = [
+  "onClick",
+  "onDoubleClick",
+  "onSubmit",
+  "onPointerDown",
+  "onPointerUp",
+  "onMouseDown",
+  "onMouseUp",
+  "onKeyDown",
+  "onKeyUp",
+  "onKeyPress",
+  "onTouchStart",
+  "onTouchEnd",
+];
+const DEFAULT_WRAPPERS = ["tracked", "trackedSubmit"];
+
+const DEV_HINT =
+  'Choose one: wrap the handler — onClick={tracked(event, props, handler)} (events: app/analytics/events.ts); mark a flow action data-analytics="flow" (the auto-instrumented funnel emits flow.<id>.<step> itself); or justify opting out data-analytics="none" data-analytics-reason="…". Decorative clicks whose handler only calls e.stopPropagation()/preventDefault() are exempt.';
+
+function attrName(attr) {
+  return attr.type === "JSXAttribute" && attr.name && attr.name.type === "JSXIdentifier"
+    ? attr.name.name
+    : null;
+}
+
+/** Static string value of an attribute, or undefined if dynamic/absent. */
+function attrStringValue(attr) {
+  const v = attr.value;
+  if (v == null) return true; // boolean shorthand `data-analytics`
+  if (v.type === "Literal") return v.value;
+  if (
+    v.type === "JSXExpressionContainer" &&
+    v.expression.type === "Literal"
+  )
+    return v.expression.value;
+  return undefined; // dynamic expression — not statically known
+}
+
+/** The CallExpression wrapping a handler, if it is tracked()/trackedSubmit(). */
+function trackedCallOf(attr, wrappers) {
+  const v = attr.value;
+  if (!v || v.type !== "JSXExpressionContainer") return null;
+  const expr = v.expression;
+  if (expr.type !== "CallExpression") return null;
+  const callee = expr.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) ? expr : null;
+}
+
+/** True if `fn`'s body does nothing but stopPropagation()/preventDefault(). */
+function isDecorativeHandler(fn) {
+  if (
+    !fn ||
+    (fn.type !== "ArrowFunctionExpression" && fn.type !== "FunctionExpression")
+  )
+    return false;
+  const isPlumbingCall = (node) =>
+    node &&
+    node.type === "CallExpression" &&
+    node.callee.type === "MemberExpression" &&
+    !node.callee.computed &&
+    node.callee.property.type === "Identifier" &&
+    (node.callee.property.name === "stopPropagation" ||
+      node.callee.property.name === "preventDefault");
+  const body = fn.body;
+  if (body.type === "CallExpression") return isPlumbingCall(body); // implicit return
+  if (body.type !== "BlockStatement") return false;
+  if (body.body.length === 0) return false;
+  return body.body.every(
+    (s) => s.type === "ExpressionStatement" && isPlumbingCall(s.expression)
+  );
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require an interactive JSX element to declare an analytics outcome: tracked() wrapper, data-analytics=\"flow\", or data-analytics=\"none\" with a reason.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          handlers: { type: "array", items: { type: "string" } },
+          wrappers: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      needsEvent: "Clickable element with no analytics outcome. " + DEV_HINT + " §3.2 stapel/clickable-needs-event",
+      noneNeedsReason:
+        'data-analytics="none" needs a non-empty data-analytics-reason="…" — the report (G5) lists deliberate opt-outs under "explicitly untracked", so the decision stays visible on review. §3.2 stapel/clickable-needs-event',
+    },
+  },
+  create(context) {
+    const settings = stapelSettings(context);
+    const handlers = new Set(
+      context.options[0]?.handlers ?? settings.clickHandlers ?? DEFAULT_HANDLERS
+    );
+    const wrappers = new Set(
+      context.options[0]?.wrappers ?? settings.trackedWrappers ?? DEFAULT_WRAPPERS
+    );
+
+    return {
+      JSXOpeningElement(node) {
+        let interactiveAttrs = [];
+        let dataAnalytics; // undefined = absent; string/true = value; null = dynamic
+        let hasReason = false;
+        for (const attr of node.attributes) {
+          const name = attrName(attr);
+          if (!name) continue; // spread attribute — can't inspect
+          if (handlers.has(name) && attr.value != null) interactiveAttrs.push(attr);
+          else if (name === "data-analytics") {
+            const val = attrStringValue(attr);
+            dataAnalytics = val === undefined ? null : val;
+          } else if (name === "data-analytics-reason") {
+            const val = attrStringValue(attr);
+            hasReason = typeof val === "string" && val.trim().length > 0;
+          }
+        }
+
+        if (interactiveAttrs.length === 0) return; // nothing to enforce
+
+        // Dynamic data-analytics value — author took explicit control we can't
+        // read statically; don't cry wolf (§3.2 syntactic-only policy).
+        if (dataAnalytics === null) return;
+
+        // (b) flow action — the machine auto-emits; satisfied.
+        if (dataAnalytics === "flow") return;
+
+        // (c) explicit opt-out — needs a reason.
+        if (dataAnalytics === "none") {
+          if (!hasReason) {
+            context.report({ node, messageId: "noneNeedsReason" });
+          }
+          return;
+        }
+
+        // (a) at least one handler is a tracked()/trackedSubmit() wrapper.
+        if (interactiveAttrs.some((a) => trackedCallOf(a, wrappers))) return;
+
+        // Exempt decorative/technical handlers (stopPropagation/preventDefault
+        // only) — plumbing, not an interaction.
+        if (
+          interactiveAttrs.every((a) => {
+            const v = a.value;
+            const fn = v && v.type === "JSXExpressionContainer" ? v.expression : null;
+            return isDecorativeHandler(fn);
+          })
+        )
+          return;
+
+        context.report({ node, messageId: "needsEvent" });
+      },
+    };
+  },
+};