@backstage/eslint-plugin 0.1.11 → 0.2.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @backstage/eslint-plugin
 
+## 0.2.0-next.0
+
+### Minor Changes
+
+- 926389b: Added `@backstage/no-ui-css-imports-in-non-frontend` rule, which ensures that CSS from `@backstage/ui` is not imported outside of the frontend app.
+
+## 0.1.12
+
+### Patch Changes
+
+- 5e98e61: Minor doc updates
+- a1dae71: Allow frontend plugin to import from another frontend plugin with same plugin id.
+
+  This prevents the ESLint rule from incorrectly flagging these imports in the new frontend system
+  where plugin override requires cross-plugin imports.
+
 ## 0.1.11
 
 ### Patch Changes

package/README.md

@@ -42,3 +42,4 @@ The following rules are provided by this plugin:
 | [@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.                                                                                           |
+| [@backstage/no-ui-css-imports-in-non-frontend](./docs/rules/no-ui-css-imports-in-non-frontend.md)   | Ensure that only packages with the `frontend` role can import CSS files from `@backstage/ui`.                            |

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

@@ -1,6 +1,25 @@
 # @backstage/no-mixed-plugin-imports
 
-Disallow mixed imports between backstage plugins.
+This rule ensures that imports between Backstage plugins are consistent with their intended usage.
+
+The rule checks the `backstage.role` field in the `package.json` of both the importing and target packages to determine if they are compatible.
+
+Plugin roles include:
+
+- `frontend-plugin` (or `frontend` for short)
+- `backend-plugin` (or `backend` for short)
+- `web-library` (or `react` for short)
+- `node-library` (or `node` for short)
+- `common-library` (or `common` for short)
+
+Prohibited imports include:
+
+- A `frontend` plugin importing directly from another `frontend`, `backend`, or `node` package. Instead, it should import from the corresponding `react` or `common` package.
+  - With an exception with the new frontend system where frontend plugins with the same plugin id are allowed to import from each other.
+- A `backend` plugin importing directly from another `backend`, `frontend`, or `react` package. Instead, it should import from the corresponding `node` or `common` package.
+- A `react` package importing from `frontend`, `backend`, or `node` packages.
+- A `node` package importing from `frontend`, `backend`, or `react` packages
+- A `common` package importing directly from any other plugin package.
 
 ## Usage
 

package/docs/rules/no-relative-monorepo-imports.md

@@ -10,7 +10,7 @@ Add the rules as follows, it has no options:
 "@backstage/no-relative-monorepo-imports": ["error"]
 ```
 
-The following patterns are considered files used during development, and only need dependencies to be declared in devDependencies:
+The following patterns are considered files used during development, and only need dependencies to be declared in `devDependencies`:
 
 ```python
 !src/**  # Any files outside of src are considered dev files

package/docs/rules/no-ui-css-imports-in-non-frontend.md

@@ -0,0 +1,50 @@
+# no-ui-css-imports-in-non-frontend
+
+Ensures that only packages with `backstage.role` set to `"frontend"` can import CSS files from `@backstage/ui`.
+
+This rule prevents non-frontend packages from accidentally importing global CSS styles from `@backstage/ui`. These CSS files should only be imported by the app, never by plugins, modules or libraries.
+
+## Rule Details
+
+This rule checks imports from `@backstage/ui` that end with `.css` and verifies that the importing package has `backstage.role: "frontend"` in its `package.json`.
+
+If a package does not have a `backstage.role` field defined at all, the import is allowed (the check is skipped).
+
+Examples of **incorrect** code for this rule:
+
+```js
+// In a package with "backstage.role": "frontend-plugin"
+import '@backstage/ui/css/styles.css';
+```
+
+```js
+// In a package with "backstage.role": "web-library"
+import '@backstage/ui/css/styles.css';
+```
+
+```js
+// In a package with "backstage.role": "backend"
+require('@backstage/ui/css/styles.css');
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// In a package with "backstage.role": "frontend"
+import '@backstage/ui/css/styles.css';
+```
+
+```js
+// In a package without a "backstage.role" field
+import '@backstage/ui/css/styles.css';
+```
+
+```js
+// Non-CSS imports are allowed in any package
+import { Button, Text } from '@backstage/ui';
+```
+
+```js
+// In a package with "backstage.role": "backend"
+import { Button } from '@backstage/ui';
+```

package/docs/rules/no-undeclared-imports.md

@@ -10,7 +10,7 @@ Add the rules as follows, it has no options:
 "@backstage/no-undeclared-imports": ["error"]
 ```
 
-The following patterns are considered files used during development, and only need dependencies to be declared in devDependencies:
+The following patterns are considered files used during development, and only need dependencies to be declared in `devDependencies`:
 
 ```python
 !src/**  # Any files outside of src are considered dev files

package/index.js

@@ -23,6 +23,7 @@ module.exports = {
         '@backstage/no-relative-monorepo-imports': 'error',
         '@backstage/no-undeclared-imports': 'error',
         '@backstage/no-mixed-plugin-imports': 'warn',
+        '@backstage/no-ui-css-imports-in-non-frontend': 'error',
       },
     },
   },
@@ -32,5 +33,6 @@ module.exports = {
     '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'),
+    'no-ui-css-imports-in-non-frontend': require('./rules/no-ui-css-imports-in-non-frontend'),
   },
 };

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, role?: string } }}} packageJson
+ * @type {import('@manypkg/get-packages').Package & { packageJson: { exports?: Record<string, string>, files?: Array<string>, backstage?: { inline?: boolean, role?: string, pluginId?: string } }}} packageJson
  */
 
 /**

package/package.json

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

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

@@ -64,6 +64,7 @@ module.exports = {
     messages: {
       forbidden:
         '{{sourcePackage}} ({{sourceRole}}) uses forbidden import from {{targetPackage}} ({{targetRole}}).',
+      useSamePluginId: `Import of {{targetPackage}} ({{targetRole}}) from {{sourceRole}} is forbidden unless you are overriding the plugin, in which case the \`backstage.pluginId\` in {{sourcePackage}}/package.json must be the same as in {{targetPackage}}`,
       useReactPlugin:
         'Use web library {{targetPackage}}-react or common library instead.',
       useNodePlugin:
@@ -146,11 +147,24 @@ module.exports = {
       }
 
       const sourceRole = pkg.packageJson.backstage?.role;
+      const sourcePluginId = pkg.packageJson.backstage?.pluginId;
       const targetRole = targetPackage.packageJson.backstage?.role;
+      const targetPluginId = targetPackage.packageJson.backstage?.pluginId;
       if (!sourceRole || !targetRole) {
         return;
       }
 
+      // Allow frontend plugins to import from other frontend plugins with the same pluginId for NFS
+      if (
+        sourceRole === 'frontend-plugin' &&
+        targetRole === 'frontend-plugin' &&
+        sourcePluginId &&
+        targetPluginId &&
+        sourcePluginId === targetPluginId
+      ) {
+        return;
+      }
+
       if (
         roleRules.some(
           rule =>
@@ -165,6 +179,19 @@ module.exports = {
           (sourceRole === 'frontend-plugin' || sourceRole === 'web-library') &&
           targetRole === 'frontend-plugin'
         ) {
+          suggest.push({
+            messageId: 'useSamePluginId',
+            data: {
+              targetPackage: targetName,
+              targetRole: targetRole,
+              sourcePackage: sourceName,
+              sourceRole: sourceRole,
+            },
+            /** @param {import('eslint').Rule.RuleFixer} _fixer */
+            fix(_fixer) {
+              // Not a fixable case, just give a suggestion to change plugin id
+            },
+          });
           suggest.push({
             messageId: 'useReactPlugin',
             data: {

package/rules/no-ui-css-imports-in-non-frontend.js

@@ -0,0 +1,77 @@
+/*
+ * 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');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      noCssImport:
+        'CSS imports from @backstage/ui are only allowed in packages with backstage.role set to "frontend". Current role: "{{role}}"',
+    },
+    docs: {
+      description:
+        'Ensure that only packages with backstage.role set to "frontend" can import CSS files from @backstage/ui.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-ui-css-imports-in-non-frontend.md',
+    },
+  },
+  create(context) {
+    const packages = getPackages(context.getCwd());
+    if (!packages) {
+      return {};
+    }
+
+    const currentPackage = packages.byPath(context.filename);
+    if (!currentPackage) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      const isBuiImport =
+        (imp.type === 'external' || imp.type === 'internal') &&
+        imp.packageName === '@backstage/ui';
+      if (!isBuiImport) {
+        return;
+      }
+
+      const isCssImport = imp.path?.endsWith('.css');
+      if (!isCssImport) {
+        return;
+      }
+
+      const backstageRole = currentPackage.packageJson.backstage?.role;
+      if (!backstageRole) {
+        // Allow if no role is defined
+        return;
+      }
+
+      if (backstageRole !== 'frontend') {
+        context.report({
+          node: node,
+          messageId: 'noCssImport',
+          data: {
+            role: backstageRole,
+          },
+        });
+      }
+    });
+  },
+};

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

@@ -1,7 +1,8 @@
 {
   "name": "@internal/bar",
   "backstage": {
-    "role": "frontend-plugin"
+    "role": "frontend-plugin",
+    "pluginId": "bar"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/__fixtures__/monorepo/packages/bar-override/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@internal/bar-override",
+  "backstage": {
+    "role": "frontend-plugin",
+    "pluginId": "bar"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./BarPage": "./src/components/Bar.tsx",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "inline-dep": "*",
+    "react-router": "*"
+  },
+  "devDependencies": {
+    "react-router-dom": "*"
+  }
+}

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

@@ -1,7 +1,8 @@
 {
   "name": "@internal/foo",
   "backstage": {
-    "role": "frontend-plugin"
+    "role": "frontend-plugin",
+    "pluginId": "foo"
   },
   "files": [
     "dist",

package/src/__fixtures__/monorepo/packages/frontend-pkg/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@internal/frontend-pkg",
+  "backstage": {
+    "role": "frontend"
+  }
+}

package/src/__fixtures__/monorepo/packages/frontend-plugin-pkg/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@internal/frontend-plugin-pkg",
+  "backstage": {
+    "role": "frontend-plugin"
+  }
+}

package/src/__fixtures__/monorepo/packages/no-role-pkg/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "@internal/no-role-pkg"
+}

package/src/no-ui-css-imports-in-non-frontend.test.ts

@@ -0,0 +1,99 @@
+/*
+ * 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-ui-css-imports-in-non-frontend';
+
+const RULE = 'no-ui-css-imports-in-non-frontend';
+const FIXTURE = path.resolve(__dirname, '__fixtures__/monorepo');
+
+const ERR = (role: string) => ({
+  message: `CSS imports from @backstage/ui are only allowed in packages with backstage.role set to "frontend". Current role: "${role}"`,
+});
+
+// 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: [
+    // Frontend package can import CSS from @backstage/ui
+    {
+      code: `import '@backstage/ui/css/styles.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-pkg/index.ts'),
+    },
+    {
+      code: `import '@backstage/ui/css/other.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-pkg/index.ts'),
+    },
+    {
+      code: `require('@backstage/ui/css/styles.css')`,
+      filename: path.join(FIXTURE, 'packages/frontend-pkg/index.ts'),
+    },
+    // Package without backstage.role can import CSS (skip check)
+    {
+      code: `import '@backstage/ui/css/styles.css'`,
+      filename: path.join(FIXTURE, 'packages/no-role-pkg/index.ts'),
+    },
+    // Non-CSS imports are allowed in any package
+    {
+      code: `import { Button } from '@backstage/ui'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+    },
+    {
+      code: `import { Text } from '@backstage/ui/components'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+    },
+    // Imports from other packages are allowed
+    {
+      code: `import './styles.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+    },
+    {
+      code: `import 'some-other-package/styles.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+    },
+  ],
+  invalid: [
+    // Backend package cannot import CSS from @backstage/ui
+    {
+      code: `import '@backstage/ui/css/styles.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+      errors: [ERR('frontend-plugin')],
+    },
+    {
+      code: `import '@backstage/ui/css/other.css'`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+      errors: [ERR('frontend-plugin')],
+    },
+    {
+      code: `require('@backstage/ui/css/styles.css')`,
+      filename: path.join(FIXTURE, 'packages/frontend-plugin-pkg/index.ts'),
+      errors: [ERR('frontend-plugin')],
+    },
+  ],
+});