Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Enforce module public APIs (#79292)

Fraser27a7dc50e673
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 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.js
index 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.js
new file mode 100644
index 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.mjs
index 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.js
new file mode 100644
index 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"]);
+ });
+});