feat: eslint rule to check forbidden plugin imports

basically verify-local-dependencies.js but done during linting also in the 3rd party repositories. Signed-off-by: Hellgren Heikki <heikki.hellgren@op.fi>
2025-06-13 01:46:04 +03:00
parent 2071dd40cf
commit 063b2d39ce
21 changed files with 429 additions and 89 deletions
@@ -41,3 +41,4 @@ The following rules are provided by this plugin:
 | [@backstage/no-relative-monorepo-imports](./docs/rules/no-relative-monorepo-imports.md)             | Forbid relative imports that reach outside of the package in a monorepo.                                                 |
 | [@backstage/no-undeclared-imports](./docs/rules/no-undeclared-imports.md)                           | Forbid imports of external packages that have not been declared in the appropriate dependencies field in `package.json`. |
 | [@backstage/no-top-level-material-ui-4-imports](./docs/rules/no-top-level-material-ui-4-imports.md) | Forbid top level import from Material UI v4 packages.                                                                    |
+| [@backstage/no-mixed-plugin-imports](./docs/rules/no-mixed-plugin-imports.md)                       | Disallow mixed plugin imports.                                                                                           |
@@ -0,0 +1,67 @@
+# @backstage/no-mixed-plugin-imports
+
+Disallow mixed imports between backstage plugins.
+
+## Usage
+
+Add the rules as follows, it has no options:
+
+```js
+"@backstage/no-mixed-plugin-imports": ["error"]
+```
+
+## Rule Details
+
+Given the following two target packages:
+
+```json
+{
+  "name": "@backstage/plugin-foo",
+  "backstage": {
+    "role": "frontend-plugin"
+  }
+}
+```
+
+```json
+{
+  "name": "@backstage/plugin-bar",
+  "backstage": {
+    "role": "frontend-plugin"
+  }
+}
+```
+
+### Fail
+
+```ts
+import { FooCard } from '@backstage/plugin-foo';
+```
+
+### Pass
+
+```ts
+import { FooCard } from '@backstage/plugin-foo-react';
+```
+
+## Options
+
+You can ignore specific target packages or files by adding them to the options in the `.eslintrc.js` file:
+
+```js
+{
+  rules: {
+    '@backstage/no-mixed-plugin-imports': [
+      'error',
+      {
+        excludedTargetPackages: [
+          '@backstage/plugin-foo',
+        ],
+        excludedFiles: [
+          '**/*.{test,spec}.[jt]s?(x)'
+        ],
+      }
+    ]
+  }
+}
+```
@@ -22,6 +22,7 @@ module.exports = {
        '@backstage/no-forbidden-package-imports': 'error',
        '@backstage/no-relative-monorepo-imports': 'error',
        '@backstage/no-undeclared-imports': 'error',
+        '@backstage/no-mixed-plugin-imports': 'error',
      },
    },
  },
@@ -30,5 +31,6 @@ module.exports = {
    'no-relative-monorepo-imports': require('./rules/no-relative-monorepo-imports'),
    'no-undeclared-imports': require('./rules/no-undeclared-imports'),
    'no-top-level-material-ui-4-imports': require('./rules/no-top-level-material-ui-4-imports'),
+    'no-mixed-plugin-imports': require('./rules/no-mixed-plugin-imports'),
  },
 };
@@ -0,0 +1,149 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// @ts-check
+
+const visitImports = require('../lib/visitImports');
+const getPackages = require('../lib/getPackages');
+const minimatch = require('minimatch');
+
+const roleRules = [
+  {
+    sourceRole: ['frontend-plugin', 'web-library'],
+    targetRole: [
+      'backend-plugin',
+      'node-library',
+      'backend-plugin-module',
+      'frontend-plugin',
+    ],
+  },
+  {
+    sourceRole: ['backend-plugin', 'node-library', 'backend-plugin-module'],
+    targetRole: ['frontend-plugin', 'web-library', 'backend-plugin'],
+  },
+  {
+    sourceRole: ['common-library'],
+    targetRole: [
+      'frontend-plugin',
+      'web-library',
+      'backend-plugin',
+      'node-library',
+      'backend-plugin-module',
+    ],
+  },
+];
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      forbidden:
+        '{{sourcePackage}} ({{sourceRole}}) uses forbidden import from {{targetPackage}} ({{targetRole}}).',
+    },
+    docs: {
+      description: 'Disallow mixed plugin imports.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-mixed-plugin-imports.md',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          excludedTargetPackages: {
+            type: 'array',
+            items: { type: 'string' },
+            uniqueItems: true,
+          },
+          excludedFiles: {
+            type: 'array',
+            items: { type: 'string' },
+            uniqueItems: true,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const packages = getPackages(context.cwd);
+    if (!packages) {
+      return {};
+    }
+
+    const filePath = context.physicalFilename
+      ? context.physicalFilename
+      : context.filename;
+
+    const pkg = packages.byPath(filePath);
+    if (!pkg) {
+      return {};
+    }
+
+    const options = context.options[0] || {};
+    const ignoreTargetPackages = options.excludedTargetPackages || [];
+    const ignorePatterns = options.excludedFiles || [
+      '**/*.{test,spec}.[jt]s?(x)',
+      '**/dev/index.[jt]s?(x)',
+    ];
+
+    if (
+      ignorePatterns.some(pattern =>
+        new minimatch.Minimatch(pattern).match(context.filename),
+      )
+    ) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'internal') {
+        return;
+      }
+
+      const targetPackage = imp.package;
+      const targetName = targetPackage.packageJson.name;
+      const sourceName = pkg.packageJson.name;
+      if (sourceName === targetName) {
+        return;
+      }
+
+      const sourceRole = pkg.packageJson.backstage?.role;
+      const targetRole = targetPackage.packageJson.backstage?.role;
+      if (!sourceRole || !targetRole) {
+        return;
+      }
+
+      if (
+        roleRules.some(
+          rule =>
+            rule.sourceRole.includes(sourceRole) &&
+            rule.targetRole.includes(targetRole) &&
+            !ignoreTargetPackages.includes(targetName),
+        )
+      ) {
+        context.report({
+          node: node,
+          messageId: 'forbidden',
+          data: {
+            sourcePackage: pkg.packageJson.name || imp.package.dir,
+            sourceRole,
+            targetPackage: targetPackage.packageJson.name || imp.package.dir,
+            targetRole,
+          },
+        });
+      }
+    });
+  },
+};
@@ -1,5 +1,12 @@
 {
  "name": "@internal/foo",
+  "backstage": {
+    "role": "frontend-plugin"
+  },
+  "files": [
+    "dist",
+    "type-utils"
+  ],
  "dependencies": {
    "@internal/bar": "1.0.0"
  },
@@ -8,9 +15,5 @@
  },
  "peerDependencies": {
    "react": "*"
-  },
-  "files": [
-    "dist",
-    "type-utils"
-  ]
+  }
 }
@@ -0,0 +1,68 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { RuleTester } from 'eslint';
+import path from 'path';
+import rule from '../rules/no-mixed-plugin-imports';
+
+const RULE = 'no-mixed-plugin-imports';
+const FIXTURE = path.resolve(__dirname, '__fixtures__/monorepo');
+
+const ERR = (
+  sourcePackage: string,
+  sourceRole: string,
+  targetPackage: string,
+  targetRole: string,
+) => ({
+  message: `${sourcePackage} (${sourceRole}) uses forbidden import from ${targetPackage} (${targetRole}).`,
+});
+
+// cwd must be restored
+const origDir = process.cwd();
+afterAll(() => {
+  process.chdir(origDir);
+});
+process.chdir(FIXTURE);
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+    ecmaVersion: 2021,
+  },
+});
+
+ruleTester.run(RULE, rule, {
+  valid: [
+    {
+      code: `import '@internal/inline'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+    },
+  ],
+  invalid: [
+    {
+      code: `import '@internal/foo'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+      errors: [
+        ERR(
+          '@internal/bar',
+          'frontend-plugin',
+          '@internal/foo',
+          'frontend-plugin',
+        ),
+      ],
+    },
+  ],
+});