From 395143466c86a27748416b7103407023398a4926 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Mon, 18 May 2026 15:43:37 +0000 Subject: [PATCH] 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 --- packages/core-eslint/base.js | 1 + packages/core-eslint/plugin.js | 2 + packages/core-eslint/rules/_manifest-ast.js | 109 +++++++++--- .../core-eslint/rules/_manifest-ast.test.js | 40 ++++- .../rules/no-undeclared-analytics-event.js | 63 +++++++ .../no-undeclared-analytics-event.test.js | 155 ++++++++++++++++++ 6 files changed, 345 insertions(+), 25 deletions(-) create mode 100644 packages/core-eslint/rules/no-undeclared-analytics-event.js create mode 100644 packages/core-eslint/rules/no-undeclared-analytics-event.test.js diff --git a/packages/core-eslint/base.js b/packages/core-eslint/base.js index 4e607ec..8cab9d7 100644 --- a/packages/core-eslint/base.js +++ b/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", diff --git a/packages/core-eslint/plugin.js b/packages/core-eslint/plugin.js index ad7280b..7acef39 100644 --- a/packages/core-eslint/plugin.js +++ b/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, diff --git a/packages/core-eslint/rules/_manifest-ast.js b/packages/core-eslint/rules/_manifest-ast.js index 11a0735..201804a 100644 --- a/packages/core-eslint/rules/_manifest-ast.js +++ b/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); } } diff --git a/packages/core-eslint/rules/_manifest-ast.test.js b/packages/core-eslint/rules/_manifest-ast.test.js index 1feb7de..014f708 100644 --- a/packages/core-eslint/rules/_manifest-ast.test.js +++ b/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: [], + }, }, }); }); diff --git a/packages/core-eslint/rules/no-undeclared-analytics-event.js b/packages/core-eslint/rules/no-undeclared-analytics-event.js new file mode 100644 index 0000000..7bdc20a --- /dev/null +++ b/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 }, + }); + } + } + }, + }; + }, +}; diff --git a/packages/core-eslint/rules/no-undeclared-analytics-event.test.js b/packages/core-eslint/rules/no-undeclared-analytics-event.test.js new file mode 100644 index 0000000..865e445 --- /dev/null +++ b/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: [], + }); + }); +});