Merge pull request #13 from typescript-eslint/example-typed-plugin

feat: add eslint-plugin-example-typed-linting

Author: JoshuaKGoldberg

package-lock.json

@@ -0,0 +1 @@
+lib

packages/eslint-plugin-example-typed-linting/.gitignore

@@ -0,0 +1,70 @@
+# `eslint-plugin-example-typed-linting`
+
+An example ESLint plugin showing typed linting with `@typescript-eslint/utils`.
+
+For documentation on custom ESLint plugins with typescript-eslint, see: <https://typescript-eslint.io/developers/custom-rules>.
+
+```js
+// eslint.config.js
+import eslint from '@eslint/js';
+import exampleTypedLinting from 'eslint-plugin-example-typed-linting'
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    { ignores: ["lib"] },
+    eslint.configs.recommended,
+    ...tseslint.configs.recommendedTypeChecked,
+    exampleTypedLinting.configs.recommended // 👈
+    {
+        languageOptions: {
+            parserOptions: {
+                projectService:true,
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+    },
+);
+```
+
+## Rules
+
+<!-- begin auto-generated rules list -->
+
+💭 Requires [type information](https://typescript-eslint.io/linting/typed-linting).
+
+| Name                                                   | Description               | 💭 |
+| :----------------------------------------------------- | :------------------------ | :- |
+| [no-loop-over-enums](docs/rules/no-loop-over-enums.md) | Avoid looping over enums. | 💭 |
+
+<!-- end auto-generated rules list -->
+
+## Development
+
+To set up this individual package, `cd` to the path to it, then install dependencies:
+
+```shell
+cd path/to/eslint-plugin-example-typed-linting
+npm i
+```
+
+Then build files into the `lib` directory with TypeScript:
+
+```shell
+npm run tsc
+```
+
+You'll then be able to run standard package scripts:
+
+- `npm run docs`: Regenerates documentation using [`eslint-doc-generator`](https://github.com/bmish/eslint-doc-generator)
+  - `npm run docs --check`: Validates that documentation is generated and up-to-date.
+- `npm run lint`: Linting this plugin itself with ESLint
+
+### Testing
+
+This example uses [Vitest](https://vitest.dev):
+
+```shell
+npm run test
+```
+
+Note that files don't need to have been built to the `lib` directory to run tests.

packages/eslint-plugin-example-typed-linting/README.md

@@ -0,0 +1,29 @@
+# Avoid looping over enums (`example-typed-linting/no-loop-over-enums`)
+
+💭 This rule requires [type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
+
+Example rule that demonstrates banning `for-in` looping over `enum`s.
+
+## Valid
+
+```ts
+const values = {};
+for (const a in values) {
+}
+```
+
+```ts
+const values = [];
+for (const a of values) {
+}
+```
+
+## Invalid
+
+```ts
+enum Values {}
+for (const a of values) {
+}
+```

packages/eslint-plugin-example-typed-linting/docs/rules/no-loop-over-enums.md

@@ -0,0 +1,21 @@
+import eslint from '@eslint/js';
+import eslintPlugin from 'eslint-plugin-eslint-plugin'
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    { ignores: ["lib"] },
+    eslint.configs.recommended,
+    ...tseslint.configs.recommendedTypeChecked,
+    eslintPlugin.configs['flat/recommended'],
+    {
+        languageOptions: {
+            parserOptions: {
+                projectService: {
+                    allowDefaultProject: ["*.config.*"],
+                    defaultProject: "tsconfig.json"
+                },
+                tsconfigRootDir: import.meta.dirname,
+            },
+        },
+    },
+);

packages/eslint-plugin-example-typed-linting/eslint.config.mjs

@@ -0,0 +1,34 @@
+{
+  "dependencies": {
+    "@typescript-eslint/utils": "8.0.0-alpha.59"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.8.0",
+    "@types/eslint": "^9.6.0",
+    "@types/eslint__js": "^8.42.3",
+    "@types/node": "^22.0.2",
+    "@typescript-eslint/rule-tester": "^8.0.0-alpha.59",
+    "eslint": "^9.8.0",
+    "eslint-doc-generator": "^1.7.1",
+    "eslint-plugin-eslint-plugin": "^6.2.0",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.0-alpha.59",
+    "vitest": "^2.0.4"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "scripts": {
+    "docs": "eslint-doc-generator",
+    "lint": "eslint",
+    "tsc": "tsc",
+    "test": "vitest"
+  },
+  "name": "eslint-plugin-example-typed-linting",
+  "type": "commonjs",
+  "version": "0.0.0"
+}

packages/eslint-plugin-example-typed-linting/package.json

@@ -0,0 +1,25 @@
+import { rules } from "./rules/index.js";
+
+const { name, version } =
+  // `import`ing here would bypass the TSConfig's `"rootDir": "src"`
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require("../package.json") as typeof import("../package.json");
+
+const plugin = {
+  configs: {
+    get recommended() {
+      return recommended;
+    },
+  },
+  meta: { name, version },
+  rules,
+};
+
+const recommended = {
+  plugins: {
+    "example-typed-linting": plugin,
+  },
+  rules,
+};
+
+export = plugin;

packages/eslint-plugin-example-typed-linting/src/index.ts

@@ -0,0 +1,5 @@
+import { rule as noLoopOverEnums } from "./no-loop-over-enum.js";
+
+export const rules = {
+  "no-loop-over-enums": noLoopOverEnums,
+};

packages/eslint-plugin-example-typed-linting/src/rules/index.ts

@@ -0,0 +1,57 @@
+import path from "node:path";
+import tseslint from "typescript-eslint";
+import { RuleTester } from "@typescript-eslint/rule-tester";
+import * as vitest from "vitest";
+
+import { rule } from "./no-loop-over-enum.js";
+
+RuleTester.afterAll = vitest.afterAll;
+RuleTester.it = vitest.it;
+RuleTester.itOnly = vitest.it.only;
+RuleTester.describe = vitest.describe;
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslint.parser,
+    parserOptions: {
+      projectService: {
+        allowDefaultProject: ["*.ts*"],
+        defaultProject: "tsconfig.json",
+      },
+      tsconfigRootDir: path.join(__dirname, "../.."),
+    },
+  },
+});
+
+ruleTester.run("no-loop-over-enum", rule, {
+  valid: [
+    `enum Values {}`,
+    `for (const a in []) {}`,
+    `for (const a of []) {}`,
+    `
+      const values = {};
+      for (const a in values) {}
+    `,
+    `
+      const values = [];
+      for (const a of values) {}
+    `,
+  ],
+  invalid: [
+    {
+      code: `
+          enum Values {}
+          for (const a in Values) {}
+      `,
+      errors: [
+        {
+          column: 27,
+          endColumn: 33,
+          line: 3,
+          endLine: 3,
+          messageId: "loopOverEnum",
+        },
+      ],
+    },
+  ],
+});

packages/eslint-plugin-example-typed-linting/src/rules/no-loop-over-enum.test.ts

@@ -0,0 +1,37 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+import * as ts from "typescript";
+
+import { createRule } from "../utils.js";
+
+export const rule = createRule({
+  create(context) {
+    const services = ESLintUtils.getParserServices(context);
+
+    return {
+      ForInStatement(node) {
+        const type = services.getTypeAtLocation(node.right);
+
+        if (type.symbol.flags & ts.SymbolFlags.Enum) {
+          context.report({
+            messageId: "loopOverEnum",
+            node: node.right,
+          });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      description: "Avoid looping over enums.",
+      recommended: true,
+      requiresTypeChecking: true,
+    },
+    messages: {
+      loopOverEnum: "Do not loop over enums.",
+    },
+    type: "suggestion",
+    schema: [],
+  },
+  name: "no-loop-over-enum",
+  defaultOptions: [],
+});

packages/eslint-plugin-example-typed-linting/src/rules/no-loop-over-enum.ts

@@ -0,0 +1,12 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+
+export interface ExampleTypedLintingRuleDocs {
+  description: string;
+  recommended?: boolean;
+  requiresTypeChecking?: boolean;
+}
+
+export const createRule = ESLintUtils.RuleCreator<ExampleTypedLintingRuleDocs>(
+  (name) =>
+    `https://github.com/typescript-eslint/examples/tree/main/eslint-plugin-example-typed-linting/docs/${name}.md`
+);

packages/eslint-plugin-example-typed-linting/src/utils.ts

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "esModuleInterop": true,
+    "module": "NodeNext",
+    "outDir": "lib",
+    "resolveJsonModule": true,
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "ES2022"
+  },
+  "include": ["src"]
+}

packages/eslint-plugin-example-typed-linting/tsconfig.json

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    exclude: ["lib"],
+  },
+});