feat(core-eslint): add no-undeclared-analytics-event ESLint rule

Adds the conformance/no-undeclared-analytics-event rule at warn severity,
mirroring no-undeclared-audit and no-undeclared-event-publish. The rule
cross-checks analytics.track("X", ...) literal slugs in *.use-case.ts
files against manifest.useCases[name].analyticsEvents, providing
sub-second editor feedback before boot-time conformance fires.

- Extends _manifest-ast.js to parse analyticsEvents arrays in both
  extractUseCaseEntry helpers
- Registers rule in plugin.js and base.js at ["warn", { repoRoot }]
- RuleTester fixtures: declared pass, undeclared warn, non-literal no-op,
  non-use-case file no-op, missing manifest entry no-op

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/core-eslint/base.js

@@ -47,6 +47,7 @@ export default [
       "conformance/required-cores-installed": ["error", { repoRoot }],
       "conformance/no-undeclared-event-publish": ["warn", { repoRoot }],
       "conformance/no-undeclared-audit": ["warn", { repoRoot }],
+      "conformance/no-undeclared-analytics-event": ["warn", { repoRoot }],
       "conformance/usecase-must-be-wired": ["error", { repoRoot }],
       "conformance/component-must-have-story": "warn",
       "conformance/component-must-have-test": "warn",

packages/core-eslint/plugin.js

@@ -3,6 +3,7 @@ import usecaseMustHaveTestFile from "./rules/usecase-must-have-test-file.js";
 import requiredCoresInstalled from "./rules/required-cores-installed.js";
 import noUndeclaredEventPublish from "./rules/no-undeclared-event-publish.js";
 import noUndeclaredAudit from "./rules/no-undeclared-audit.js";
+import noUndeclaredAnalyticsEvent from "./rules/no-undeclared-analytics-event.js";
 import usecaseMustBeWired from "./rules/usecase-must-be-wired.js";
 import componentMustHaveStory from "./rules/component-must-have-story.js";
 import componentMustHaveTest from "./rules/component-must-have-test.js";
@@ -29,6 +30,7 @@ const plugin = {
     "required-cores-installed": requiredCoresInstalled,
     "no-undeclared-event-publish": noUndeclaredEventPublish,
     "no-undeclared-audit": noUndeclaredAudit,
+    "no-undeclared-analytics-event": noUndeclaredAnalyticsEvent,
     "usecase-must-be-wired": usecaseMustBeWired,
     "component-must-have-story": componentMustHaveStory,
     "component-must-have-test": componentMustHaveTest,

packages/core-eslint/rules/_manifest-ast.js

@@ -18,7 +18,12 @@ export function parseManifestUseCases(manifestPath) {
   }
   let ast;
   try {
-    ast = parse(src, { sourceType: "module", ecmaVersion: "latest", loc: false, range: false });
+    ast = parse(src, {
+      sourceType: "module",
+      ecmaVersion: "latest",
+      loc: false,
+      range: false,
+    });
   } catch {
     return null;
   }
@@ -27,13 +32,19 @@ export function parseManifestUseCases(manifestPath) {
   const arg = unwrapAsConst(defineCall.arguments[0]);
   if (!arg || arg.type !== "ObjectExpression") return null;
   const useCasesProp = arg.properties.find(
-    (p) => p.type === "Property" && p.key.type === "Identifier" && p.key.name === "useCases",
+    (p) =>
+      p.type === "Property" &&
+      p.key.type === "Identifier" &&
+      p.key.name === "useCases",
   );
-  if (!useCasesProp || useCasesProp.value.type !== "ObjectExpression") return {};
+  if (!useCasesProp || useCasesProp.value.type !== "ObjectExpression")
+    return {};
   const result = {};
   for (const entry of useCasesProp.value.properties) {
-    if (entry.type !== "Property" || entry.value.type !== "ObjectExpression") continue;
-    const name = entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
+    if (entry.type !== "Property" || entry.value.type !== "ObjectExpression")
+      continue;
+    const name =
+      entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
     result[name] = extractUseCaseEntry(entry.value);
   }
   return result;
@@ -46,7 +57,11 @@ function findDefineFeatureCall(ast) {
     for (const decl of node.declaration.declarations) {
       const init = decl.init;
       if (!init) continue;
-      if (init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "defineFeature") {
+      if (
+        init.type === "CallExpression" &&
+        init.callee.type === "Identifier" &&
+        init.callee.name === "defineFeature"
+      ) {
         return init;
       }
     }
@@ -60,15 +75,29 @@ function unwrapAsConst(node) {
 }
 
 function extractUseCaseEntry(objExpr) {
-  const entry = { mutates: false, audits: [], publishes: [], consumes: [] };
+  const entry = {
+    mutates: false,
+    audits: [],
+    publishes: [],
+    consumes: [],
+    analyticsEvents: [],
+  };
   for (const prop of objExpr.properties) {
     if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
     const key = prop.key.name;
     if (key === "mutates" && prop.value.type === "Literal") {
       entry.mutates = prop.value.value === true;
-    } else if ((key === "audits" || key === "publishes" || key === "consumes") && prop.value.type === "ArrayExpression") {
+    } else if (
+      (key === "audits" ||
+        key === "publishes" ||
+        key === "consumes" ||
+        key === "analyticsEvents") &&
+      prop.value.type === "ArrayExpression"
+    ) {
       entry[key] = prop.value.elements
-        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
+        .filter(
+          (el) => el && el.type === "Literal" && typeof el.value === "string",
+        )
         .map((el) => el.value);
     }
   }
@@ -94,7 +123,12 @@ export function parseManifestFully(manifestPath) {
   }
   let ast;
   try {
-    ast = parse(src, { sourceType: "module", ecmaVersion: "latest", loc: false, range: false });
+    ast = parse(src, {
+      sourceType: "module",
+      ecmaVersion: "latest",
+      loc: false,
+      range: false,
+    });
   } catch {
     return null;
   }
@@ -109,16 +143,33 @@ export function parseManifestFully(manifestPath) {
 
   for (const prop of arg.properties) {
     if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
-    if (prop.key.name === "name" && prop.value.type === "Literal" && typeof prop.value.value === "string") {
+    if (
+      prop.key.name === "name" &&
+      prop.value.type === "Literal" &&
+      typeof prop.value.value === "string"
+    ) {
       name = prop.value.value;
-    } else if (prop.key.name === "requiredCores" && prop.value.type === "ArrayExpression") {
+    } else if (
+      prop.key.name === "requiredCores" &&
+      prop.value.type === "ArrayExpression"
+    ) {
       requiredCores = prop.value.elements
-        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
+        .filter(
+          (el) => el && el.type === "Literal" && typeof el.value === "string",
+        )
         .map((el) => el.value);
-    } else if (prop.key.name === "useCases" && prop.value.type === "ObjectExpression") {
+    } else if (
+      prop.key.name === "useCases" &&
+      prop.value.type === "ObjectExpression"
+    ) {
       for (const entry of prop.value.properties) {
-        if (entry.type !== "Property" || entry.value.type !== "ObjectExpression") continue;
-        const ucName = entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
+        if (
+          entry.type !== "Property" ||
+          entry.value.type !== "ObjectExpression"
+        )
+          continue;
+        const ucName =
+          entry.key.type === "Identifier" ? entry.key.name : entry.key.value;
         useCases[ucName] = extractUseCaseEntryFromObj(entry.value);
       }
     }
@@ -137,7 +188,11 @@ function findDefineFeatureCallFromBody(ast) {
     for (const decl of node.declaration.declarations) {
       const init = decl.init;
       if (!init) continue;
-      if (init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "defineFeature") {
+      if (
+        init.type === "CallExpression" &&
+        init.callee.type === "Identifier" &&
+        init.callee.name === "defineFeature"
+      ) {
         return init;
       }
     }
@@ -151,15 +206,29 @@ function unwrapAsConstNode(node) {
 }
 
 function extractUseCaseEntryFromObj(objExpr) {
-  const entry = { mutates: false, audits: [], publishes: [], consumes: [] };
+  const entry = {
+    mutates: false,
+    audits: [],
+    publishes: [],
+    consumes: [],
+    analyticsEvents: [],
+  };
   for (const prop of objExpr.properties) {
     if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
     const key = prop.key.name;
     if (key === "mutates" && prop.value.type === "Literal") {
       entry.mutates = prop.value.value === true;
-    } else if ((key === "audits" || key === "publishes" || key === "consumes") && prop.value.type === "ArrayExpression") {
+    } else if (
+      (key === "audits" ||
+        key === "publishes" ||
+        key === "consumes" ||
+        key === "analyticsEvents") &&
+      prop.value.type === "ArrayExpression"
+    ) {
       entry[key] = prop.value.elements
-        .filter((el) => el && el.type === "Literal" && typeof el.value === "string")
+        .filter(
+          (el) => el && el.type === "Literal" && typeof el.value === "string",
+        )
         .map((el) => el.value);
     }
   }

packages/core-eslint/rules/_manifest-ast.test.js

@@ -36,9 +36,27 @@ describe("parseManifestUseCases", () => {
   jobs: [],
 } as const);`);
     expect(parseManifestUseCases(fp)).toEqual({
-      signIn: { mutates: false, audits: [], publishes: [], consumes: [] },
-      signUp: { mutates: true, audits: ["user.created"], publishes: ["auth.signed-up"], consumes: [] },
-      signOut: { mutates: true, audits: ["session.ended"], publishes: [], consumes: [] },
+      signIn: {
+        mutates: false,
+        audits: [],
+        publishes: [],
+        consumes: [],
+        analyticsEvents: [],
+      },
+      signUp: {
+        mutates: true,
+        audits: ["user.created"],
+        publishes: ["auth.signed-up"],
+        consumes: [],
+        analyticsEvents: [],
+      },
+      signOut: {
+        mutates: true,
+        audits: ["session.ended"],
+        publishes: [],
+        consumes: [],
+        analyticsEvents: [],
+      },
     });
   });
 
@@ -69,8 +87,20 @@ describe("parseManifestFully", () => {
       name: "auth",
       requiredCores: ["audit", "events"],
       useCases: {
-        signIn: { mutates: false, audits: [], publishes: [], consumes: [] },
-        signUp: { mutates: true, audits: ["user.created"], publishes: [], consumes: [] },
+        signIn: {
+          mutates: false,
+          audits: [],
+          publishes: [],
+          consumes: [],
+          analyticsEvents: [],
+        },
+        signUp: {
+          mutates: true,
+          audits: ["user.created"],
+          publishes: [],
+          consumes: [],
+          analyticsEvents: [],
+        },
       },
     });
   });

packages/core-eslint/rules/no-undeclared-analytics-event.js

@@ -0,0 +1,63 @@
+import { parseManifestUseCases } from "./_manifest-ast.js";
+import { useCaseNameFromFile } from "./_usecase-name.js";
+import {
+  manifestPathForFeature,
+  featureRootForFile,
+} from "./_manifest-source.js";
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        'analytics.track("X") inside a use-case factory must declare X in manifest.useCases[name].analyticsEvents.',
+    },
+    schema: [
+      {
+        type: "object",
+        properties: { repoRoot: { type: "string" } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      undeclared:
+        '{{useCase}} calls analytics.track("{{event}}") but {{event}} is not declared in manifest.useCases.{{useCase}}.analyticsEvents. Add it to the manifest or remove the call.',
+    },
+  },
+  create(context) {
+    const opts = context.options[0] ?? {};
+    const repoRoot = opts.repoRoot ?? context.cwd ?? process.cwd();
+    const filename = context.filename;
+    const useCaseName = useCaseNameFromFile(filename);
+    if (!useCaseName) return {};
+    const featureRoot = featureRootForFile(filename, repoRoot);
+    if (!featureRoot) return {};
+    const manifest = parseManifestUseCases(manifestPathForFeature(featureRoot));
+    if (!manifest || !manifest[useCaseName]) return {};
+    const declared = new Set(manifest[useCaseName].analyticsEvents ?? []);
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === "MemberExpression" &&
+          node.callee.object.type === "Identifier" &&
+          node.callee.object.name === "analytics" &&
+          node.callee.property.type === "Identifier" &&
+          node.callee.property.name === "track" &&
+          node.arguments.length > 0 &&
+          node.arguments[0].type === "Literal" &&
+          typeof node.arguments[0].value === "string"
+        ) {
+          const event = node.arguments[0].value;
+          if (!declared.has(event)) {
+            context.report({
+              node,
+              messageId: "undeclared",
+              data: { event, useCase: useCaseName },
+            });
+          }
+        }
+      },
+    };
+  },
+};

packages/core-eslint/rules/no-undeclared-analytics-event.test.js

@@ -0,0 +1,155 @@
+import { describe, it } from "vitest";
+import { RuleTester } from "eslint";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import rule from "./no-undeclared-analytics-event.js";
+
+function makeFixture({ manifestUseCases, useCaseBody }) {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nuae-"));
+  const featureDir = path.join(repoRoot, "packages", "demo");
+  fs.mkdirSync(path.join(featureDir, "src", "application", "use-cases"), {
+    recursive: true,
+  });
+  const useCasesObj = Object.entries(manifestUseCases)
+    .map(
+      ([name, uc]) =>
+        `    ${name}: { mutates: ${uc.mutates}, audits: [], publishes: [], consumes: [], analyticsEvents: [${uc.analyticsEvents.map((e) => `"${e}"`).join(", ")}] },`,
+    )
+    .join("\n");
+  fs.writeFileSync(
+    path.join(featureDir, "src", "feature.manifest.ts"),
+    `export const demoManifest = defineFeature({
+  name: "demo",
+  requiredCores: [],
+  useCases: {
+${useCasesObj}
+  },
+  realtimeChannels: [],
+  jobs: [],
+} as const);`,
+  );
+  const useCaseFile = path.join(
+    featureDir,
+    "src",
+    "application",
+    "use-cases",
+    "sign-up.use-case.ts",
+  );
+  fs.writeFileSync(useCaseFile, useCaseBody);
+  return { repoRoot, useCaseFile };
+}
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser: await import("@typescript-eslint/parser"),
+    ecmaVersion: "latest",
+    sourceType: "module",
+  },
+});
+
+describe("no-undeclared-analytics-event", () => {
+  it("passes when analytics.track slug matches manifest analyticsEvents[]", () => {
+    const { repoRoot, useCaseFile } = makeFixture({
+      manifestUseCases: {
+        signUp: { mutates: true, analyticsEvents: ["user.signed-up"] },
+      },
+      useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
+    });
+    tester.run("no-undeclared-analytics-event", rule, {
+      valid: [
+        {
+          filename: useCaseFile,
+          code: fs.readFileSync(useCaseFile, "utf8"),
+          options: [{ repoRoot }],
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  it("fires when analytics.track slug is not in manifest", () => {
+    const { repoRoot, useCaseFile } = makeFixture({
+      manifestUseCases: { signUp: { mutates: true, analyticsEvents: [] } },
+      useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
+    });
+    tester.run("no-undeclared-analytics-event", rule, {
+      valid: [],
+      invalid: [
+        {
+          filename: useCaseFile,
+          code: fs.readFileSync(useCaseFile, "utf8"),
+          options: [{ repoRoot }],
+          errors: [
+            {
+              messageId: "undeclared",
+              data: { event: "user.signed-up", useCase: "signUp" },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("is a no-op when analytics.track is called with a non-literal argument", () => {
+    const { repoRoot, useCaseFile } = makeFixture({
+      manifestUseCases: { signUp: { mutates: true, analyticsEvents: [] } },
+      useCaseBody: `export const signUpUseCase = (analytics, slug) => async () => { analytics.track(slug, {}); };`,
+    });
+    tester.run("no-undeclared-analytics-event", rule, {
+      valid: [
+        {
+          filename: useCaseFile,
+          code: fs.readFileSync(useCaseFile, "utf8"),
+          options: [{ repoRoot }],
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  it("is a no-op for files that are not use-case files", () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), "nuae-"));
+    const featureDir = path.join(repoRoot, "packages", "demo");
+    fs.mkdirSync(path.join(featureDir, "src", "application"), {
+      recursive: true,
+    });
+    const controllerFile = path.join(
+      featureDir,
+      "src",
+      "application",
+      "sign-up.controller.ts",
+    );
+    fs.writeFileSync(
+      controllerFile,
+      `export const signUpController = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
+    );
+    tester.run("no-undeclared-analytics-event", rule, {
+      valid: [
+        {
+          filename: controllerFile,
+          code: fs.readFileSync(controllerFile, "utf8"),
+          options: [{ repoRoot }],
+        },
+      ],
+      invalid: [],
+    });
+  });
+
+  it("is a no-op when manifest has no entry for the use case", () => {
+    const { repoRoot, useCaseFile } = makeFixture({
+      manifestUseCases: {},
+      useCaseBody: `export const signUpUseCase = (analytics) => async () => { analytics.track("user.signed-up", {}); };`,
+    });
+    tester.run("no-undeclared-analytics-event", rule, {
+      valid: [
+        {
+          filename: useCaseFile,
+          code: fs.readFileSync(useCaseFile, "utf8"),
+          options: [{ repoRoot }],
+        },
+      ],
+      invalid: [],
+    });
+  });
+});