From ef73e8626bf906febc682f1f31451a4668e329c3 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 3 Feb 2023 17:04:24 +0100
Subject: [PATCH] eslint-plugin: add docs for no-undeclared-imports

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../docs/rules/no-undeclared-imports.md       | 84 +++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 packages/eslint-plugin/docs/rules/no-undeclared-imports.md

diff --git a/packages/eslint-plugin/docs/rules/no-undeclared-imports.md b/packages/eslint-plugin/docs/rules/no-undeclared-imports.md
new file mode 100644
index 0000000000..6102c772e6
--- /dev/null
+++ b/packages/eslint-plugin/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';
+```