@backstage/eslint-plugin 0.0.0-nightly-20230207022622

package/.eslintrc.js

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+
+// Custom lint config here since source is ES5
+module.exports = {
+  plugins: ['@backstage'],
+  env: {
+    node: true,
+    es2021: true,
+  },
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2018,
+    sourceType: 'module',
+    lib: require('@backstage/cli/config/tsconfig.json').compilerOptions.lib,
+  },
+  rules: {
+    '@backstage/no-undeclared-imports': ['error'],
+    'no-unused-expressions': 'off',
+  },
+};

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @backstage/eslint-plugin
+
+## 0.0.0-nightly-20230207022622
+
+### Minor Changes
+
+- 179d301518: Added a new ESLint plugin with common rules for Backstage projects. See the [README](https://github.com/import-js/eslint-plugin-import/blob/main/packages/eslint-plugin/README.md) for more details.

package/README.md

@@ -0,0 +1,42 @@
+# @backstage/eslint-plugin
+
+A collection of ESLint rules useful to Backstage projects.
+
+## Usage
+
+This ESLint plugin is part of the default lint configuration provided by the [Backstage CLI](https://www.npmjs.com/package/@backstage/cli), so you generally do not need to install it manually.
+
+If you do wish to install this plugin manually, start by adding it as a development dependency to your project:
+
+```sh
+yarn add --dev @backstage/eslint-plugin
+```
+
+Then add it to your ESLint configuration:
+
+```js
+extends: [
+  'plugin:@backstage/recommended',
+],
+```
+
+Alternatively, if you want to install in individual rules manually:
+
+```js
+plugins: [
+  '@backstage',
+],
+rules: {
+  '@backstage/no-forbidden-package-imports': 'error',
+}
+```
+
+## Rules
+
+The following rules are provided by this plugin:
+
+| Rule                                                                                    | Description                                                                                                              |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| [@backstage/no-forbidden-package-imports](./docs/rules/no-forbidden-package-imports.md) | Disallow internal monorepo imports from package subpaths that are not exported.                                          |
+| [@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`. |

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

@@ -0,0 +1,52 @@
+# @backstage/no-forbidden-package-imports
+
+Disallow internal monorepo imports from package subpaths that are not exported.
+
+## Usage
+
+Add the rules as follows, it has no options:
+
+```js
+"@backstage/no-forbidden-package-imports": ["error"]
+```
+
+## Rule Details
+
+Given the following two target packages:
+
+```json
+{
+  "name": "@backstage/plugin-foo",
+  "files": ["dist", "type-utils"]
+}
+```
+
+```json
+{
+  "name": "@backstage/plugin-bar",
+  "exports": {
+    ".": "./src/index.ts",
+    "./testUtils": "./src/testUtils/index.ts",
+    "./package.json": "./package.json"
+  }
+}
+```
+
+### Fail
+
+```ts
+import { FooCard } from '@backstage/plugin-foo/src/components';
+import { BarCard } from '@backstage/plugin-bar/src/components';
+```
+
+### Pass
+
+```ts
+import { FooCard } from '@backstage/plugin-foo';
+import { FooType } from '@backstage/plugin-foo/type-utils';
+import fooPkg from '@backstage/plugin-foo/package.json';
+
+import { BarCard } from '@backstage/plugin-bar';
+import { renderBarCardExtension } from '@backstage/plugin-bar/testUtils';
+import barPkg from '@backstage/plugin-bar/package.json';
+```

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

@@ -0,0 +1,43 @@
+# @backstage/no-relative-monorepo-imports
+
+Forbid relative imports that reach outside of the package in a monorepo.
+
+## Usage
+
+Add the rules as follows, it has no options:
+
+```js
+"@backstage/no-relative-monorepo-imports": ["error"]
+```
+
+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
+src/**/*.test.*
+src/**/*.stories.*
+src/**/__testUtils__/**
+src/**/__mocks__/**
+src/setupTests.*
+```
+
+## Rule Details
+
+Assuming an import from for example `plugins/bar/src/index.ts`:
+
+### Fail
+
+```ts
+import { FooCard } from '../../foo';
+
+import { FooCard } from '../../foo/src/components/FooCard';
+```
+
+### Pass
+
+```ts
+import { FooCard } from '@internal/plugin-foo';
+
+// This is allowed by this rule, but not by no-forbidden-package-imports
+import { FooCard } from '@internal/plugin-foo/src/components/FooCard';
+```

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

@@ -0,0 +1,84 @@
+# @backstage/no-undeclared-imports
+
+Forbid imports of external packages that have not been declared in the appropriate dependencies field in `package.json`.
+
+## Usage
+
+Add the rules as follows, it has no options:
+
+```js
+"@backstage/no-undeclared-imports": ["error"]
+```
+
+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
+src/**/*.test.*
+src/**/*.stories.*
+src/**/__testUtils__/**
+src/**/__mocks__/**
+src/setupTests.*
+```
+
+## Rule Details
+
+Given the following `package.json`:
+
+```json
+{
+  "name": "@backstage/plugin-foo",
+  "backstage": {
+    "role": "frontend-plugin"
+  },
+  "dependencies": {
+    "react": "^17.0.0"
+  },
+  "devDependencies": {
+    "@backstage/core-plugin-api": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@backstage/config": "*"
+  }
+}
+```
+
+### Fail
+
+Inside `src/my-plugin.ts`:
+
+```ts
+// Should be declared as a dependency
+const _ = require('lodash');
+import _ from 'lodash';
+
+// React should be a peer dependency in frontend plugins
+import react from 'react';
+
+// Should be declared as a dependency, not a dev dependency
+import { useApi } from '@backstage/core-plugin-api';
+```
+
+Inside `src/my-plugin.test.ts` (a test file):
+
+```ts
+// Should be declared as a dev dependency
+const _ = require('lodash');
+import _ from 'lodash';
+```
+
+### Pass
+
+Inside `src/my-plugin.ts`:
+
+```ts
+// Declared in peerDependencies, so it is allowed
+import { ConfigReader } from '@backstage/config';
+```
+
+Inside `src/my-plugin.test.ts` (a test file):
+
+```ts
+// Declared as a dev dependency inside a test file
+import { useApi } from '@backstage/core-plugin-api';
+```

package/index.js

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+module.exports = {
+  configs: {
+    recommended: {
+      plugins: ['@backstage'],
+      rules: {
+        '@backstage/no-forbidden-package-imports': 'error',
+        '@backstage/no-relative-monorepo-imports': 'error',
+        '@backstage/no-undeclared-imports': 'error',
+      },
+    },
+  },
+  rules: {
+    'no-forbidden-package-imports': require('./rules/no-forbidden-package-imports'),
+    'no-relative-monorepo-imports': require('./rules/no-relative-monorepo-imports'),
+    'no-undeclared-imports': require('./rules/no-undeclared-imports'),
+  },
+};

package/lib/getPackages.js

@@ -0,0 +1,71 @@
+/*
+ * 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 path = require('path');
+const manypkg = require('@manypkg/get-packages');
+
+/**
+ * @typedef ExtendedPackage
+ * @type {import('@manypkg/get-packages').Package & { packageJson: { exports?: Record<string, string>, files?: Array<string> }}} packageJson
+ */
+
+/**
+ * @typedef PackageMap
+ * @type object
+ *
+ * @property {ExtendedPackage} root
+ * @property {ExtendedPackage[]} list
+ * @property {Map<string, ExtendedPackage>} map
+ * @property {(path: string) => ExtendedPackage | undefined} byPath
+ */
+
+// Loads all packages in the monorepo once, and caches the result
+module.exports = (function () {
+  /** @type {PackageMap | undefined} */
+  let result = undefined;
+  /** @type {number} */
+  let lastLoadAt = 0;
+
+  /** @returns {PackageMap | undefined} */
+  return function getPackages(/** @type {string} */ dir) {
+    if (result) {
+      // Only cache for 5 seconds, to avoid the need to reload ESLint servers
+      if (Date.now() - lastLoadAt > 5000) {
+        result = undefined;
+      } else {
+        return result;
+      }
+    }
+    const packages = manypkg.getPackagesSync(dir);
+    if (!packages) {
+      return undefined;
+    }
+    result = {
+      map: new Map(packages.packages.map(pkg => [pkg.packageJson.name, pkg])),
+      list: packages.packages,
+      root: packages.root,
+      byPath(filePath) {
+        return packages.packages.find(
+          pkg => !path.relative(pkg.dir, filePath).startsWith('..'),
+        );
+      },
+    };
+    lastLoadAt = Date.now();
+    return result;
+  };
+})();

package/lib/visitImports.js

@@ -0,0 +1,173 @@
+/*
+ * 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 { builtinModules } = require('module');
+const getPackages = require('./getPackages');
+
+/**
+ * @typedef LocalImport
+ * @type {object}
+ * @property {'local'} type
+ * @property {'value' | 'type'} kind
+ * @property {string} path
+ */
+
+/**
+ * @typedef InternalImport
+ * @type {object}
+ * @property {'internal'} type
+ * @property {'value' | 'type'} kind
+ * @property {string} path
+ * @property {import('./getPackages').ExtendedPackage} package
+ */
+
+/**
+ * @typedef ExternalImport
+ * @type {object}
+ * @property {'external'} type
+ * @property {'value' | 'type'} kind
+ * @property {string} path
+ * @property {string} packageName
+ */
+
+/**
+ * @typedef BuiltinImport
+ * @type {object}
+ * @property {'builtin'} type
+ * @property {'value' | 'type'} kind
+ * @property {string} path
+ * @property {string} packageName
+ */
+
+/**
+ * @callback ImportVisitor
+ * @param {ConsideredNode} node
+ * @param {LocalImport | InternalImport | ExternalImport | BuiltinImport} import
+ */
+
+/**
+ * @typedef ConsideredNode
+ * @type {import('estree').ImportDeclaration | import('estree').ExportAllDeclaration | import('estree').ExportNamedDeclaration | import('estree').ImportExpression | import('estree').SimpleCallExpression}
+ */
+
+/**
+ * @param {ConsideredNode} node
+ * @returns {undefined | {path: string, kind: 'type' | 'value'}}
+ */
+function getImportInfo(node) {
+  /** @type {import('estree').Expression | import('estree').SpreadElement | undefined | null} */
+  let pathNode;
+
+  if (node.type === 'CallExpression') {
+    if (
+      node.callee.type === 'Identifier' &&
+      node.callee.name == 'require' &&
+      node.arguments.length === 1
+    ) {
+      pathNode = node.arguments[0];
+    }
+  } else {
+    pathNode = node.source;
+  }
+
+  if (pathNode?.type !== 'Literal') {
+    return undefined;
+  }
+  if (typeof pathNode.value !== 'string') {
+    return undefined;
+  }
+
+  /** @type {any} */
+  const anyNode = node;
+  return { path: pathNode.value, kind: anyNode.importKind ?? 'value' };
+}
+
+/**
+ * @param visitor - Visitor callback
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ImportVisitor} visitor
+ */
+module.exports = function visitImports(context, visitor) {
+  const packages = getPackages(context.getCwd());
+  if (!packages) {
+    return;
+  }
+
+  /**
+   * @param {ConsideredNode} node
+   */
+  function visit(node) {
+    const info = getImportInfo(node);
+    if (!info) {
+      return;
+    }
+
+    if (info.path[0] === '.') {
+      return visitor(node, { type: 'local', ...info });
+    }
+
+    const pathParts = info.path.split('/');
+
+    // Check for match with plain name, then namespaced name
+    let packageName;
+    let subPath;
+    if (info.path[0] === '@') {
+      packageName = pathParts.slice(0, 2).join('/');
+      subPath = pathParts.slice(2).join('/');
+    } else {
+      packageName = pathParts[0];
+      subPath = pathParts.slice(1).join('/');
+    }
+    const pkg = packages?.map.get(packageName);
+    if (!pkg) {
+      if (
+        packageName.startsWith('node:') ||
+        builtinModules.includes(packageName)
+      ) {
+        return visitor(node, {
+          type: 'builtin',
+          kind: info.kind,
+          path: subPath,
+          packageName,
+        });
+      }
+
+      return visitor(node, {
+        type: 'external',
+        kind: info.kind,
+        path: subPath,
+        packageName,
+      });
+    }
+
+    return visitor(node, {
+      type: 'internal',
+      kind: info.kind,
+      path: subPath,
+      package: pkg,
+    });
+  }
+
+  return {
+    ImportDeclaration: visit,
+    ExportAllDeclaration: visit,
+    ExportNamedDeclaration: visit,
+    ImportExpression: visit,
+    CallExpression: visit,
+  };
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@backstage/eslint-plugin",
+  "description": "Backstage ESLint plugin",
+  "version": "0.0.0-nightly-20230207022622",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/eslint-plugin"
+  },
+  "license": "Apache-2.0",
+  "main": "./index.js",
+  "scripts": {
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test"
+  },
+  "dependencies": {
+    "@manypkg/get-packages": "^1.1.3",
+    "minimatch": "^5.1.2"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.0.0-nightly-20230207022622",
+    "eslint": "^8.33.0"
+  }
+}

package/rules/no-forbidden-package-imports.js

@@ -0,0 +1,74 @@
+/*
+ * 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');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      forbidden: '{{packageName}} does not export {{subPath}}',
+    },
+    docs: {
+      description:
+        'Disallow internal monorepo imports from package subpaths that are not exported.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-forbidden-package-imports.md',
+    },
+  },
+  create(context) {
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'internal') {
+        return;
+      }
+      // Empty subpaths are always allowed
+      if (!imp.path) {
+        return;
+      }
+
+      // If the import is listed in the package.json exports field, we allow it
+      const exp = imp.package.packageJson.exports;
+      if (exp && (exp[imp.path] || exp['./' + imp.path])) {
+        return;
+      }
+      if (!exp) {
+        // If there's no exports field, we allow anything listed in files, except dist
+        const files = imp.package.packageJson.files;
+        if (
+          !files ||
+          files.some(f => !f.startsWith('dist') && imp.path.startsWith(f))
+        ) {
+          return;
+        }
+        // And also package.json
+        if (imp.path === 'package.json') {
+          return;
+        }
+      }
+
+      context.report({
+        node: node,
+        messageId: 'forbidden',
+        data: {
+          packageName: imp.package.packageJson.name || imp.package.dir,
+          subPath: imp.path,
+        },
+      });
+    });
+  },
+};