The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Enforce module public APIs (#79292)
Fraser27a7dc50e673
diff --git a/eslint.config.mjs b/eslint.config.mjsindex 7506231b868..555ea4eada6 100644--- a/eslint.config.mjs+++ b/eslint.config.mjs@@ -27,6 +27,7 @@ import metabasePlugin from "./frontend/lint/eslint-plugin-metabase/index.js";import {elements as boundaryElements,enforcedRules as boundaryRules,+ getPublicApiModules,} from "./frontend/lint/module-boundaries.mjs";const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -295,6 +296,7 @@ const configs = [],plugins: {boundaries,+ metabase: metabasePlugin,},settings: {"boundaries/elements": boundaryElements,@@ -309,6 +311,12 @@ const configs = [message: "${file.type} cannot import from ${dependency.type}",},],+ // Modules flagged `enforcePublicApi` in module-boundaries.mjs must be imported through their index.+ // Their own files must import relatively.+ "metabase/enforce-module-public-api": [+ "error",+ { modules: getPublicApiModules() },+ ],// Every file frontend/src/ and enterprise/frontend/src/ must belong to a declared module."boundaries/no-unknown-files": "error",},diff --git a/frontend/lint/eslint-plugin-metabase/index.js b/frontend/lint/eslint-plugin-metabase/index.jsindex 57daa3c533c..61c3fffc940 100644--- a/frontend/lint/eslint-plugin-metabase/index.js+++ b/frontend/lint/eslint-plugin-metabase/index.js@@ -8,6 +8,7 @@ module.exports = {version: "1.0.0",},rules: {+ "enforce-module-public-api": require("./rules/enforce-module-public-api"),"jtag-missing-key": require("./rules/jtag-missing-key"),"no-color-literals": require("./rules/no-color-literals"),"no-direct-helper-import": require("./rules/no-direct-helper-import"),diff --git a/frontend/lint/eslint-plugin-metabase/rules/enforce-module-public-api.js b/frontend/lint/eslint-plugin-metabase/rules/enforce-module-public-api.jsnew file mode 100644index 00000000000..985a61599ae--- /dev/null+++ b/frontend/lint/eslint-plugin-metabase/rules/enforce-module-public-api.js@@ -0,0 +1,95 @@+/**+ * @fileoverview Modules flagged `enforcePublicApi` in module-boundaries.mjs must be imported through their index.+ * Their own files must import relatively — importing the module's own alias creates a self-cycle through the index.+ * The modules arrive as rule options because this plugin is CJS and the registry is ESM.+ */++module.exports = {+ meta: {+ type: "problem",+ docs: {+ description:+ "Enforce importing modules with a public API through their index",+ category: "Best Practices",+ recommended: true,+ },+ schema: [+ {+ type: "object",+ properties: {+ modules: {+ type: "array",+ // Import aliases of module roots, e.g. "metabase/analytics"+ items: { type: "string" },+ },+ },+ additionalProperties: false,+ },+ ],+ messages: {+ useModuleIndex:+ "Import from the module's public interface ('{{alias}}') instead of a file inside it.",+ useRelativeImport:+ "Files inside a module must use relative imports, not the module's own '{{alias}}' alias.",+ },+ },+ create(context) {+ const modules = (context.options[0] && context.options[0].modules) || [];+ if (modules.length === 0) {+ return {};+ }++ // Longest alias first, so a nested module wins over its parent when both match.+ const aliases = [...modules].sort((a, b) => b.length - a.length);++ const filename = context.filename.replaceAll("\\", "/");+ const owningAlias = aliases.find((alias) =>+ filename.includes(`/frontend/src/${alias}/`),+ );++ const checkSource = (sourceNode) => {+ const source = sourceNode && sourceNode.value;+ if (typeof source !== "string") {+ return;+ }+ const target = aliases.find(+ (alias) => source === alias || source.startsWith(`${alias}/`),+ );+ if (!target) {+ return;+ }+ if (target === owningAlias) {+ context.report({+ node: sourceNode,+ messageId: "useRelativeImport",+ data: { alias: target },+ });+ return;+ }+ if (source !== target) {+ context.report({+ node: sourceNode,+ messageId: "useModuleIndex",+ data: { alias: target },+ });+ }+ };++ return {+ ImportDeclaration(node) {+ checkSource(node.source);+ },+ ExportNamedDeclaration(node) {+ if (node.source) {+ checkSource(node.source);+ }+ },+ ExportAllDeclaration(node) {+ checkSource(node.source);+ },+ ImportExpression(node) {+ checkSource(node.source);+ },+ };+ },+};diff --git a/frontend/lint/module-boundaries.mjs b/frontend/lint/module-boundaries.mjsindex 4e4c3cd5269..ebbb0bc161b 100644--- a/frontend/lint/module-boundaries.mjs+++ b/frontend/lint/module-boundaries.mjs@@ -4,16 +4,29 @@ const createElement = ({pattern,mode,enforceOutgoing = true,-}) => ({- type: `${type}/${name}`,- pattern: pattern ?? `frontend/src/metabase/${name}/**`,- ...(mode && { mode }),- enforceOutgoing,-});+ // Outside code must import the module root alias, and the module's own files must import relatively.+ // Enforced by the `metabase/enforce-module-public-api` rule via `getPublicApiModules` below.+ enforcePublicApi = false,+}) => {+ if (enforcePublicApi && (pattern || mode)) {+ // Single-file elements are their own entry point, and elements outside the+ // `metabase` alias root would need their own alias derivation.+ throw new Error(+ `enforcePublicApi requires a default folder element (frontend/src/metabase/<name>/**): ${name}`,+ );+ }+ return {+ type: `${type}/${name}`,+ pattern: pattern ?? `frontend/src/metabase/${name}/**`,+ ...(mode && { mode }),+ enforceOutgoing,+ ...(enforcePublicApi && { publicApiAlias: `metabase/${name}` }),+ };+};const elements = [// lib- createElement({ type: "lib", name: "analytics" }),+ createElement({ type: "lib", name: "analytics", enforcePublicApi: true }),createElement({ type: "lib", name: "css" }),createElement({type: "lib",@@ -444,4 +457,16 @@ function getFeatureModules(els = elements) {return els.map((e) => e.type).filter((type) => type.startsWith("feature/"));}-export { elements, rules, enforcedRules, getFeatureModules };+// The import aliases of the modules flagged `enforcePublicApi`, for the+// `metabase/enforce-module-public-api` rule.+function getPublicApiModules(els = elements) {+ return els.map((element) => element.publicApiAlias).filter(Boolean);+}++export {+ elements,+ rules,+ enforcedRules,+ getFeatureModules,+ getPublicApiModules,+};diff --git a/frontend/lint/tests/enforce-module-public-api.unit.spec.js b/frontend/lint/tests/enforce-module-public-api.unit.spec.jsnew file mode 100644index 00000000000..f4fa8a7f8cc--- /dev/null+++ b/frontend/lint/tests/enforce-module-public-api.unit.spec.js@@ -0,0 +1,161 @@+import { RuleTester } from "eslint";++import rule from "../eslint-plugin-metabase/rules/enforce-module-public-api";+import { getPublicApiModules } from "../module-boundaries.mjs";++const ruleTester = new RuleTester({+ languageOptions: { ecmaVersion: 2022, sourceType: "module" },+});++const options = [{ modules: ["metabase/analytics"] }];++const OUTSIDE_FILE = "/repo/frontend/src/metabase/admin/some-file.ts";+const INSIDE_FILE = "/repo/frontend/src/metabase/analytics/event.ts";++ruleTester.run("enforce-module-public-api", rule, {+ valid: [+ {+ name: "outside files import the module index",+ code: `import { trackSimpleEvent } from "metabase/analytics";`,+ filename: OUTSIDE_FILE,+ options,+ },+ {+ name: "module files import relatively",+ code: `import { createSnowplowTracker } from "./snowplow";`,+ filename: INSIDE_FILE,+ options,+ },+ {+ name: "unrelated deep imports are not the rule's business",+ code: `import { useToast } from "metabase/common/hooks/use-toast";`,+ filename: OUTSIDE_FILE,+ options,+ },+ {+ name: "an alias sharing the module prefix is not the module",+ code: `import { x } from "metabase/analytics-page/util";`,+ filename: OUTSIDE_FILE,+ options,+ },+ {+ name: "no flagged modules, no checks",+ code: `import { trackSchemaEvent } from "metabase/analytics/event";`,+ filename: OUTSIDE_FILE,+ options: [{ modules: [] }],+ },+ ],+ invalid: [+ {+ name: "outside files must not deep-import module files",+ code: `import { trackSchemaEvent } from "metabase/analytics/event";`,+ filename: OUTSIDE_FILE,+ options,+ errors: [{ messageId: "useModuleIndex" }],+ },+ {+ name: "re-exports count as imports",+ code: `export * from "metabase/analytics/event";`,+ filename: OUTSIDE_FILE,+ options,+ errors: [{ messageId: "useModuleIndex" }],+ },+ {+ name: "dynamic imports count as imports",+ code: `const load = () => import("metabase/analytics/snowplow");`,+ filename: OUTSIDE_FILE,+ options,+ errors: [{ messageId: "useModuleIndex" }],+ },+ {+ name: "module files must not deep-import via their own alias",+ code: `import { trackPageView } from "metabase/analytics/page-view";`,+ filename: INSIDE_FILE,+ options,+ errors: [{ messageId: "useRelativeImport" }],+ },+ {+ name: "module files must not import their own index (self-cycle)",+ code: `import { trackSimpleEvent } from "metabase/analytics";`,+ filename: INSIDE_FILE,+ options,+ errors: [{ messageId: "useRelativeImport" }],+ },+ ],+});++// Parent-first on purpose: resolution must not depend on option order.+const nestedOptions = [+ { modules: ["metabase/admin", "metabase/admin/performance"] },+];+const NESTED_CHILD_FILE =+ "/repo/frontend/src/metabase/admin/performance/StrategyForm.ts";+// OUTSIDE_FILE sits inside `metabase/admin`, so the nested cases need a file outside both modules.+const NESTED_OUTSIDE_FILE = "/repo/frontend/src/metabase/home/some-file.ts";++ruleTester.run("enforce-module-public-api nested modules", rule, {+ valid: [+ {+ name: "the child's index is the child's interface, not a parent deep import",+ code: `import { StrategyForm } from "metabase/admin/performance";`,+ filename: NESTED_OUTSIDE_FILE,+ options: nestedOptions,+ },+ {+ name: "child files may import the parent's index",+ code: `import { getAdminPaths } from "metabase/admin";`,+ filename: NESTED_CHILD_FILE,+ options: nestedOptions,+ },+ ],+ invalid: [+ {+ name: "deep imports of the child are attributed to the child",+ code: `import { x } from "metabase/admin/performance/utils";`,+ filename: NESTED_OUTSIDE_FILE,+ options: nestedOptions,+ errors: [+ {+ messageId: "useModuleIndex",+ data: { alias: "metabase/admin/performance" },+ },+ ],+ },+ {+ name: "deep imports of the parent are attributed to the parent",+ code: `import { x } from "metabase/admin/utils";`,+ filename: NESTED_OUTSIDE_FILE,+ options: nestedOptions,+ errors: [+ { messageId: "useModuleIndex", data: { alias: "metabase/admin" } },+ ],+ },+ {+ name: "child files must not import their own index",+ code: `import { StrategyForm } from "metabase/admin/performance";`,+ filename: NESTED_CHILD_FILE,+ options: nestedOptions,+ errors: [+ {+ messageId: "useRelativeImport",+ data: { alias: "metabase/admin/performance" },+ },+ ],+ },+ ],+});++describe("getPublicApiModules", () => {+ it("returns the aliases of flagged elements only", () => {+ expect(+ getPublicApiModules([+ {+ type: "lib",+ pattern: "frontend/src/metabase/flagged/**",+ publicApiAlias: "metabase/flagged",+ },+ { type: "shared", pattern: "frontend/src/metabase/unflagged/**" },+ ]),+ ).toEqual(["metabase/flagged"]);+ });+});