@backstage/eslint-plugin 0.0.0-nightly-20230207022622

package/rules/no-relative-monorepo-imports.js

@@ -0,0 +1,85 @@
+/*
+ * 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 visitImports = require('../lib/visitImports');
+const getPackageMap = require('../lib/getPackages');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      outside: 'Import of {{path}} is outside of any known monorepo package',
+      forbidden:
+        "Relative imports of monorepo packages are forbidden, use '{{newImport}}' instead",
+    },
+    docs: {
+      description:
+        'Forbid relative imports that reach outside of the package in a monorepo.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-relative-monorepo-imports.md',
+    },
+  },
+  create(context) {
+    const packages = getPackageMap(context.getCwd());
+    if (!packages) {
+      return {};
+    }
+    const filePath = context.getPhysicalFilename
+      ? context.getPhysicalFilename()
+      : context.getFilename();
+
+    const localPkg = packages.byPath(filePath);
+    if (!localPkg) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'local') {
+        return;
+      }
+
+      const target = path.resolve(path.dirname(filePath), imp.path);
+      if (!path.relative(localPkg.dir, target).startsWith('..')) {
+        return;
+      }
+
+      const targetPkg = packages.byPath(target);
+      if (!targetPkg) {
+        context.report({
+          node: node,
+          messageId: 'outside',
+          data: {
+            path: target,
+          },
+        });
+        return;
+      }
+
+      const targetPath = path.relative(targetPkg.dir, target);
+      const targetName = targetPkg.packageJson.name ?? '<unknown>';
+      context.report({
+        node: node,
+        messageId: 'forbidden',
+        data: {
+          newImport: targetPath ? `${targetName}/${targetPath}` : targetName,
+        },
+      });
+    });
+  },
+};

package/rules/no-undeclared-imports.js

@@ -0,0 +1,205 @@
+/*
+ * 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 getPackageMap = require('../lib/getPackages');
+const visitImports = require('../lib/visitImports');
+const minimatch = require('minimatch');
+
+const depFields = {
+  dep: 'dependencies',
+  dev: 'devDependencies',
+  peer: 'peerDependencies',
+};
+
+const devModulePatterns = [
+  new minimatch.Minimatch('!src/**'),
+  new minimatch.Minimatch('src/**/*.test.*'),
+  new minimatch.Minimatch('src/**/*.stories.*'),
+  new minimatch.Minimatch('src/**/__testUtils__/**'),
+  new minimatch.Minimatch('src/**/__mocks__/**'),
+  new minimatch.Minimatch('src/setupTests.*'),
+];
+
+function getExpectedDepType(
+  /** @type {any} */ localPkg,
+  /** @type {string} */ impPath,
+  /** @type {string} */ modulePath,
+) {
+  const role = localPkg?.backstage?.role;
+  // Some package roles have known dependency types
+  switch (role) {
+    case 'common-library':
+    case 'web-library':
+    case 'frontend-plugin':
+    case 'frontend-plugin-module':
+    case 'node-library':
+    case 'backend-plugin':
+    case 'backend-plugin-module':
+      switch (impPath) {
+        case 'react':
+        case 'react-dom':
+        case 'react-router':
+        case 'react-router-dom':
+          return 'peer';
+      }
+      break;
+    case 'cli':
+    case 'frontend':
+    case 'backend':
+    default:
+      break;
+  }
+
+  for (const pattern of devModulePatterns) {
+    if (pattern.match(modulePath)) {
+      return 'dev';
+    }
+  }
+  return 'dep';
+}
+
+/**
+ *
+ * @param {import('@manypkg/get-packages').Package['packageJson']} pkg
+ * @param {string} name
+ * @param {ReturnType<typeof getExpectedDepType>} expectedType
+ * @returns {{oldDepsField?: string, depsField: string} | undefined}
+ */
+function findConflict(pkg, name, expectedType) {
+  const isDep = pkg.dependencies?.[name];
+  const isDevDep = pkg.devDependencies?.[name];
+  const isPeerDep = pkg.peerDependencies?.[name];
+  const depsField = depFields[expectedType];
+
+  if (expectedType === 'dep' && !isDep && !isPeerDep) {
+    const oldDepsField = isDevDep ? depFields.dev : undefined;
+    return { oldDepsField, depsField };
+  } else if (expectedType === 'dev' && !isDevDep && !isDep && !isPeerDep) {
+    return { oldDepsField: undefined, depsField };
+  } else if (expectedType === 'peer' && !isPeerDep) {
+    const oldDepsField = isDep
+      ? depFields.dep
+      : isDevDep
+      ? depFields.dev
+      : undefined;
+
+    return { oldDepsField, depsField };
+  }
+  return undefined;
+}
+
+/**
+ * @param {string} depsField
+ */
+function getAddFlagForDepsField(depsField) {
+  switch (depsField) {
+    case depFields.dep:
+      return '';
+    case depFields.dev:
+      return ' --dev';
+    case depFields.peer:
+      return ' --peer';
+    default:
+      return '';
+  }
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      undeclared:
+        "{{ packageName }} must be declared in {{ depsField }} of {{ packageJsonPath }}, run 'yarn --cwd {{ packagePath }} add{{ addFlag }} {{ packageName }}' from the project root.",
+      switch:
+        '{{ packageName }} is declared in {{ oldDepsField }}, but should be moved to {{ depsField }} in {{ packageJsonPath }}.',
+    },
+    docs: {
+      description:
+        'Forbid imports of external packages that have not been declared in the appropriate dependencies field in `package.json`.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-undeclared-imports.md',
+    },
+  },
+  create(context) {
+    const packages = getPackageMap(context.getCwd());
+    if (!packages) {
+      return {};
+    }
+    const filePath = context.getPhysicalFilename
+      ? context.getPhysicalFilename()
+      : context.getFilename();
+
+    const localPkg = packages.byPath(filePath);
+    if (!localPkg) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'external') {
+        return;
+      }
+      // We leave checking of type imports to the repo-tools check
+      if (imp.kind === 'type') {
+        return;
+      }
+
+      const modulePath = path.relative(localPkg.dir, filePath);
+      const expectedType = getExpectedDepType(
+        localPkg.packageJson,
+        imp.packageName,
+        modulePath,
+      );
+
+      const conflict = findConflict(
+        localPkg.packageJson,
+        imp.packageName,
+        expectedType,
+      );
+
+      if (conflict) {
+        try {
+          const fullImport = imp.path
+            ? `${imp.packageName}/${imp.path}`
+            : imp.packageName;
+          require.resolve(fullImport, {
+            paths: [localPkg.dir],
+          });
+        } catch {
+          // If the dependency doesn't resolve then it's likely a type import, ignore
+          return;
+        }
+
+        const packagePath = path.relative(packages.root.dir, localPkg.dir);
+        const packageJsonPath = path.join(packagePath, 'package.json');
+
+        context.report({
+          node,
+          messageId: conflict.oldDepsField ? 'switch' : 'undeclared',
+          data: {
+            ...conflict,
+            packagePath,
+            addFlag: getAddFlagForDepsField(conflict.depsField),
+            packageName: imp.packageName,
+            packageJsonPath: packageJsonPath,
+          },
+        });
+      }
+    });
+  },
+};

package/src/__fixtures__/monorepo/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "root",
+  "workspaces": [
+    "packages/*"
+  ]
+}

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

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

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

@@ -0,0 +1,16 @@
+{
+  "name": "@internal/foo",
+  "dependencies": {
+    "@internal/bar": "1.0.0"
+  },
+  "devDependencies": {
+    "lodash": "*"
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "files": [
+    "dist",
+    "type-utils"
+  ]
+}

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

@@ -0,0 +1,120 @@
+/*
+ * 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-forbidden-package-imports';
+
+const RULE = 'no-forbidden-package-imports';
+const FIXTURE = path.resolve(__dirname, '__fixtures__/monorepo');
+
+const ERR = (name: string, path: string) => ({
+  message: `${name} does not export ${path}`,
+});
+
+process.chdir(FIXTURE);
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+    ecmaVersion: 2021,
+  },
+});
+
+ruleTester.run(RULE, rule, {
+  valid: [
+    {
+      code: `import '@internal/foo'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/foo/type-utils'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/foo/type-utils/anything'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/foo/package.json'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/bar'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/bar/package.json'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+    {
+      code: `import '@internal/bar/BarPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+    },
+  ],
+  invalid: [
+    {
+      code: `import '@internal/foo/FooPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/foo', 'FooPage')],
+    },
+    {
+      code: `import '@internal/foo/dist'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/foo', 'dist')],
+    },
+    {
+      code: `import '@internal/foo/dist/FooPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/foo', 'dist/FooPage')],
+    },
+    {
+      code: `import '@internal/foo/src/FooPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/foo', 'src/FooPage')],
+    },
+    {
+      code: `import '@internal/foo/src'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/foo', 'src')],
+    },
+    {
+      code: `import '@internal/bar/OtherBarPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/bar', 'OtherBarPage')],
+    },
+    {
+      code: `import '@internal/bar/dist'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/bar', 'dist')],
+    },
+    {
+      code: `import '@internal/bar/dist/BarPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/bar', 'dist/BarPage')],
+    },
+    {
+      code: `import '@internal/bar/src/BarPage'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/bar', 'src/BarPage')],
+    },
+    {
+      code: `import '@internal/bar/src'`,
+      filename: path.join(FIXTURE, 'index.ts'),
+      errors: [ERR('@internal/bar', 'src')],
+    },
+  ],
+});

package/src/no-relative-monorepo-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-relative-monorepo-imports';
+
+const RULE = 'no-relative-monorepo-imports';
+const FIXTURE = path.resolve(__dirname, '__fixtures__/monorepo');
+
+const ERR_OUTSIDE = (path: string) => ({
+  message: `Import of ${path} is outside of any known monorepo package`,
+});
+const ERR_FORBIDDEN = (newImp: string) => ({
+  message: `Relative imports of monorepo packages are forbidden, use '${newImp}' instead`,
+});
+
+process.chdir(FIXTURE);
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    sourceType: 'module',
+    ecmaVersion: 2021,
+  },
+});
+
+ruleTester.run(RULE, rule, {
+  valid: [
+    {
+      code: `import { version } from '@internal/foo'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+    },
+    {
+      code: `import { version } from '@internal/foo/src'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+    },
+  ],
+  invalid: [
+    {
+      code: `import { version } from '../../foo'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+      errors: [ERR_FORBIDDEN('@internal/foo')],
+    },
+    {
+      code: `import { version } from '../../foo/src'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+      errors: [ERR_FORBIDDEN('@internal/foo/src')],
+    },
+    {
+      code: `import { version } from '../../../package.json'`,
+      filename: path.join(FIXTURE, 'packages/bar/src/index.ts'),
+      errors: [ERR_OUTSIDE(path.join(FIXTURE, 'package.json'))],
+    },
+  ],
+});