@backstage/eslint-plugin 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @backstage/eslint-plugin
 
+## 0.1.11
+
+### Patch Changes
+
+- 098ef95: Fix custom rules package scanning performance.
+- 063b2d3: Added new eslint rule to restrict mixed plugin imports.
+
+  New rule `@backstage/no-mixed-plugin-imports` disallows mixed imports between plugins that are mixing
+  the backstage architecture. This rule forces that:
+
+  - No imports from frontend plugins to backend plugins or other frontend plugins.
+  - No imports from backend plugins to frontend plugins or other backend plugins.
+  - No imports from common plugins to frontend or backend plugins.
+
+  The current recommended configuration is giving a warning for mixed imports. This is to be changed in
+  the future to an error so please adjust your workspace accordingly.
+
+## 0.1.11-next.0
+
+### Patch Changes
+
+- 098ef95: Fix custom rules package scanning performance.
+
 ## 0.1.10
 
 ### Patch Changes

package/README.md

@@ -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.                                                                                           |

package/docs/rules/no-mixed-plugin-imports.md

@@ -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)'
+        ],
+      }
+    ]
+  }
+}
+```

package/index.js

@@ -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': 'warn',
       },
     },
   },
@@ -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'),
   },
 };

package/knip-report.md

@@ -1,9 +1,2 @@
 # Knip report
 
-## Unlisted dependencies (2)
-
-| Name   | Location                       | Severity |
-| :----- | :----------------------------- | :------- |
-| estree | rules/no-undeclared-imports.js | error    |
-| estree | lib/visitImports.js            | error    |
-

package/lib/getPackages.js

@@ -21,7 +21,7 @@ const manypkg = require('@manypkg/get-packages');
 
 /**
  * @typedef ExtendedPackage
- * @type {import('@manypkg/get-packages').Package & { packageJson: { exports?: Record<string, string>, files?: Array<string>, backstage?: { inline?: boolean } }}} packageJson
+ * @type {import('@manypkg/get-packages').Package & { packageJson: { exports?: Record<string, string>, files?: Array<string>, backstage?: { inline?: boolean, role?: string } }}} packageJson
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/eslint-plugin",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Backstage ESLint plugin",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "minimatch": "^9.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.28.0",
+    "@backstage/cli": "^0.33.0",
     "@types/estree": "^1.0.5",
     "eslint": "^8.33.0"
   }

package/rules/no-mixed-plugin-imports.js

@@ -0,0 +1,249 @@
+/*
+ * 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');
+
+/** @typedef {import('../lib/getPackages.js').ExtendedPackage} ExtendedPackage */
+
+/**
+ * @param {string} pattern
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+const matchesPattern = (pattern, filePath) => {
+  return new minimatch.Minimatch(pattern).match(filePath);
+};
+
+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}}).',
+      useReactPlugin:
+        'Use web library {{targetPackage}}-react or common library instead.',
+      useNodePlugin:
+        'Use node library {{targetPackage}}-node or common library instead.',
+      useCommonPlugin: 'Use common library {{targetPackage}}-common instead.',
+      removeImport:
+        'Remove this import to avoid mixed plugin imports. Fix the code by refactoring it to use the correct plugin type.',
+    },
+    docs: {
+      description: 'Disallow mixed plugin imports.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-mixed-plugin-imports.md',
+    },
+    hasSuggestions: true,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          excludedTargetPackages: {
+            type: 'array',
+            items: { type: 'string' },
+            uniqueItems: true,
+          },
+          excludedFiles: {
+            type: 'array',
+            items: { type: 'string' },
+            uniqueItems: true,
+          },
+          includedFiles: {
+            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;
+
+    /** @type {ExtendedPackage | undefined} */
+    const pkg = packages.byPath(filePath);
+    if (!pkg) {
+      return {};
+    }
+
+    const options = context.options[0] || {};
+    /** @type {string[]} */
+    const ignoreTargetPackages = options.excludedTargetPackages || [];
+    /** @type {string[]} */
+    const excludePatterns = options.excludedFiles || [];
+    /** @type {string[]} */
+    const includePatterns = options.includedFiles || ['**/src/**'];
+
+    if (
+      !includePatterns.some(pattern => matchesPattern(pattern, filePath)) ||
+      excludePatterns.some(pattern => matchesPattern(pattern, filePath))
+    ) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'internal') {
+        return;
+      }
+
+      /** @type {ExtendedPackage | undefined} */
+      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),
+        )
+      ) {
+        const suggest = [];
+
+        if (
+          (sourceRole === 'frontend-plugin' || sourceRole === 'web-library') &&
+          targetRole === 'frontend-plugin'
+        ) {
+          suggest.push({
+            messageId: 'useReactPlugin',
+            data: {
+              targetPackage: targetName,
+            },
+            /** @param {import('eslint').Rule.RuleFixer} fixer */
+            fix(fixer) {
+              const source = context.sourceCode;
+              const nodeSource = source.getText(imp.node);
+              const newImport = nodeSource.replace(/'$/, "-react'");
+              return fixer.replaceText(imp.node, newImport);
+            },
+          });
+          suggest.push({
+            messageId: 'useCommonPlugin',
+            data: {
+              targetPackage: targetName,
+            },
+            /** @param {import('eslint').Rule.RuleFixer} fixer */
+            fix(fixer) {
+              const source = context.sourceCode;
+              const nodeSource = source.getText(imp.node);
+              const newImport = nodeSource.replace(/'$/, "-common'");
+              return fixer.replaceText(imp.node, newImport);
+            },
+          });
+        } else if (
+          (sourceRole === 'backend-plugin' ||
+            sourceRole === 'backend-plugin-module') &&
+          targetRole === 'backend-plugin'
+        ) {
+          suggest.push({
+            messageId: 'useNodePlugin',
+            data: {
+              targetPackage: targetName,
+            },
+            /** @param {import('eslint').Rule.RuleFixer} fixer */
+            fix(fixer) {
+              const source = context.sourceCode;
+              const nodeSource = source.getText(imp.node);
+              const newImport = nodeSource.replace(/-backend'$/, "-node'");
+              return fixer.replaceText(imp.node, newImport);
+            },
+          });
+          suggest.push({
+            messageId: 'useCommonPlugin',
+            data: {
+              targetPackage: targetName,
+            },
+            /** @param {import('eslint').Rule.RuleFixer} fixer */
+            fix(fixer) {
+              const source = context.sourceCode;
+              const nodeSource = source.getText(imp.node);
+              const newImport = nodeSource.replace(/-backend'$/, '-common');
+              return fixer.replaceText(imp.node, newImport);
+            },
+          });
+        } else {
+          suggest.push({
+            messageId: 'removeImport',
+            /** @param {import('eslint').Rule.RuleFixer} _fixer */
+            fix(_fixer) {
+              // Not a fixable case, just give a suggestion to remove the import
+            },
+          });
+        }
+
+        context.report({
+          node: node,
+          messageId: 'forbidden',
+          data: {
+            sourcePackage: pkg.packageJson.name || imp.package.dir,
+            sourceRole,
+            targetPackage: targetPackage.packageJson.name || imp.package.dir,
+            targetRole,
+          },
+          suggest,
+        });
+      }
+    });
+  },
+};

package/rules/no-undeclared-imports.js

@@ -319,6 +319,7 @@ module.exports = {
         if (importsToAdd.length > 0) {
           addMissingImports(importsToAdd, packages, localPkg);
 
+          packages.clearCache();
           // This switches all import directives back to the original import.
           for (const added of importsToAdd) {
             context.report({
@@ -336,6 +337,7 @@ module.exports = {
           removeInlineImports(importsToInline, localPkg);
           addForwardedInlineImports(importsToInline, localPkg);
 
+          packages.clearCache();
           for (const inlined of importsToInline) {
             context.report({
               node: inlined.node,
@@ -350,8 +352,6 @@ module.exports = {
           }
           importsToInline.length = 0;
         }
-
-        packages.clearCache();
       },
       ...visitImports(context, (node, imp) => {
         // We leave checking of type imports to the repo-tools check,

package/src/__fixtures__/monorepo/packages/foo/package.json

@@ -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"
-  ]
+  }
 }

package/src/no-mixed-plugin-imports.test.ts

@@ -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',
+        ),
+      ],
+    },
+  ],
+});

package/src/no-undeclared-imports.test.ts

@@ -24,6 +24,7 @@ jest.mock('child_process', () => ({
 
 const RULE = 'no-undeclared-imports';
 const FIXTURE = joinPath(__dirname, '__fixtures__/monorepo');
+//
 
 const ERR_UNDECLARED = (
   name: string,
@@ -246,26 +247,14 @@ ruleTester.run(RULE, rule, {
     },
     {
       code: `import 'react-dom'`,
-      output: `import 'directive:add-import:dependencies:react-dom'`,
+      output: `import 'directive:add-import:peerDependencies:react-dom'`,
       filename: joinPath(FIXTURE, 'packages/foo/src/index.ts'),
       errors: [
         ERR_UNDECLARED(
           'react-dom',
-          'dependencies',
-          joinPath('packages', 'foo'),
-        ),
-      ],
-    },
-    {
-      code: `import 'react-dom'`,
-      output: `import 'directive:add-import:devDependencies:react-dom'`,
-      filename: joinPath(FIXTURE, 'packages/foo/src/index.test.ts'),
-      errors: [
-        ERR_UNDECLARED(
-          'react-dom',
-          'devDependencies',
+          'peerDependencies',
           joinPath('packages', 'foo'),
-          '--dev',
+          '--peer',
         ),
       ],
     },