fix(eslint-plugin-qwik): fix ESLint 9 compatibility, improve typing and docs

Author: better-salmon

.changeset/giant-lobsters-sip.md

@@ -0,0 +1,5 @@
+---
+'eslint-plugin-qwik': patch
+---
+
+Fix ESLint 9 compatibility, enhance typing and README.

packages/eslint-plugin-qwik/README.md

@@ -1,6 +1,109 @@
 # eslint-plugin-qwik
 
-## Implemented
+Qwik comes with its own set of ESLint rules to help developers write better code.
 
-- `no-use-after-await` (deprecated)
-- `valid-lexical-scope`
+## Usage
+
+Install the plugin:
+
+```bash
+npm add -D eslint-plugin-qwik
+pnpm add -D eslint-plugin-qwik
+yarn add -D eslint-plugin-qwik
+```
+
+> `eslint-plugin-qwik` uses the tsc typechecker to type information. You must include the `tsconfigRootDir` in the `parserOptions`.
+
+## Configurations
+
+### Flat config (recommended)
+
+```js
+// eslint.config.js
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import { qwikEslint9Plugin } from 'eslint-plugin-qwik';
+
+export const qwikConfig = [
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
+    languageOptions: {
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+  },
+  ...qwikEslint9Plugin.configs.recommended,
+  {
+    ignores: ['node_modules/*', 'dist/*', 'server/*', 'tmp/*'],
+  },
+];
+```
+
+> `ignores` must always be the last configuration in the array. Note that in shared configs, the `ignores` must be defined where the config is used, not in the shared config.
+
+### Legacy config (`eslint < 9`)
+
+```js
+// .eslintrc.js
+module.exports = {
+  env: {
+    browser: true,
+    es2021: true,
+    node: true,
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:qwik/recommended',
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+    ecmaVersion: 2021,
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+  plugins: ['@typescript-eslint'],
+};
+```
+
+> To ignore files, you must use the `.eslintignore` file.
+
+## List of supported rules
+
+- **Warn** in 'recommended' ruleset — ✔️
+- **Error** in 'recommended' ruleset — ✅
+- **Warn** in 'strict' ruleset — 🔒
+- **Error** in 'strict' ruleset — 🔐
+- **Typecheck** — 💭
+
+| Rule                                                                                     | Description                                                                                                                                                            | Ruleset  |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| [`qwik/valid-lexical-scope`](https://qwik.dev/docs/advanced/eslint/#valid-lexical-scope) | Used the tsc typechecker to detect the capture of unserializable data in dollar `($)` scopes.                                                                          | ✅ 🔐 💭 |
+| [`qwik/use-method-usage`](https://qwik.dev/docs/advanced/eslint/#use-method-usage)       | Detect invalid use of use hook.                                                                                                                                        | ✅ 🔐    |
+| [`qwik/no-react-props`](https://qwik.dev/docs/advanced/eslint/#no-react-props)           | Disallow usage of React-specific `className/htmlFor` props.                                                                                                            | ✅ 🔐    |
+| [`qwik/loader-location`](https://qwik.dev/docs/advanced/eslint/#loader-location)         | Detect declaration location of `loader$`.                                                                                                                              | ✔️ 🔐    |
+| [`qwik/prefer-classlist`](https://qwik.dev/docs/advanced/eslint/#prefer-classlist)       | Enforce using the `classlist` prop over importing a `classnames` helper. The `classlist` prop accepts an object `{ [class: string]: boolean }` just like `classnames`. | ✔️ 🔐    |
+| [`qwik/jsx-no-script-url`](https://qwik.dev/docs/advanced/eslint/#jsx-no-script-url)     | Disallow javascript: URLs.                                                                                                                                             | ✔️ 🔐    |
+| [`qwik/jsx-key`](https://qwik.dev/docs/advanced/eslint/#jsx-key)                         | Disallow missing `key` props in iterators/collection literals.                                                                                                         | ✔️ 🔐    |
+| [`qwik/unused-server`](https://qwik.dev/docs/advanced/eslint/#unused-server)             | Detect unused `server$()` functions.                                                                                                                                   | ✅ 🔐    |
+| [`qwik/jsx-img`](https://qwik.dev/docs/advanced/eslint/#jsx-img)                         | For performance reasons, always provide width and height attributes for `<img>` elements, it will help to prevent layout shifts.                                       | ✔️ 🔐    |
+| [`qwik/jsx-a`](https://qwik.dev/docs/advanced/eslint/#jsx-a)                             | For a perfect SEO score, always provide href attribute for `<a>` elements.                                                                                             | ✔️ 🔐    |
+| [`qwik/no-use-visible-task`](https://qwik.dev/docs/advanced/eslint/#no-use-visible-task) | Detect `useVisibleTask$()` functions.                                                                                                                                  | ✔️ 🔒    |

packages/eslint-plugin-qwik/index.ts

@@ -1,3 +1,4 @@
+import type { TSESLint } from '@typescript-eslint/utils';
 import { jsxAtag } from './src/jsxAtag';
 import { jsxImg } from './src/jsxImg';
 import { jsxKey } from './src/jsxKey';
@@ -11,76 +12,69 @@ import { useMethodUsage } from './src/useMethodUsage';
 import { validLexicalScope } from './src/validLexicalScope';
 import pkg from './package.json';
 
+type Rules = NonNullable<TSESLint.FlatConfig.Plugin['rules']>;
+
 const rules = {
-  'use-method-usage': useMethodUsage,
   'valid-lexical-scope': validLexicalScope,
-  'loader-location': loaderLocation,
+  'use-method-usage': useMethodUsage,
   'no-react-props': noReactProps,
+  'loader-location': loaderLocation,
   'prefer-classlist': preferClasslist,
   'jsx-no-script-url': jsxNoScriptUrl,
   'jsx-key': jsxKey,
   'unused-server': unusedServer,
   'jsx-img': jsxImg,
   'jsx-a': jsxAtag,
   'no-use-visible-task': noUseVisibleTask,
-};
+} as const satisfies Rules;
 
-const recommendedRules = {
-  'qwik/use-method-usage': 'error',
+const recommendedRulesLevels = {
   'qwik/valid-lexical-scope': 'error',
+  'qwik/use-method-usage': 'error',
   'qwik/no-react-props': 'error',
+  'qwik/loader-location': 'warn',
   'qwik/prefer-classlist': 'warn',
   'qwik/jsx-no-script-url': 'warn',
-  'qwik/loader-location': 'warn',
   'qwik/jsx-key': 'warn',
   'qwik/unused-server': 'error',
   'qwik/jsx-img': 'warn',
   'qwik/jsx-a': 'warn',
   'qwik/no-use-visible-task': 'warn',
-};
-const strictRules = {
+} as const satisfies TSESLint.FlatConfig.Rules;
+
+const strictRulesLevels = {
   'qwik/valid-lexical-scope': 'error',
   'qwik/use-method-usage': 'error',
-  'qwik/loader-location': 'error',
   'qwik/no-react-props': 'error',
+  'qwik/loader-location': 'error',
   'qwik/prefer-classlist': 'error',
   'qwik/jsx-no-script-url': 'error',
   'qwik/jsx-key': 'error',
   'qwik/unused-server': 'error',
   'qwik/jsx-img': 'error',
   'qwik/jsx-a': 'error',
   'qwik/no-use-visible-task': 'warn',
-};
+} as const satisfies TSESLint.FlatConfig.Rules;
 
 const configs = {
   recommended: {
     plugins: ['qwik'],
-    rules: recommendedRules,
+    rules: recommendedRulesLevels,
   },
   strict: {
     plugins: ['qwik'],
-    rules: strictRules,
+    rules: strictRulesLevels,
   },
-};
+} as const satisfies Record<string, TSESLint.ClassicConfig.Config>;
 
-const qwikEslint9Plugin = {
+const qwikEslint9Plugin: TSESLint.FlatConfig.Plugin = {
   configs: {
-    recommended: [
-      {
-        plugins: {
-          qwik: this,
-        },
-        rules: recommendedRules,
-      },
-    ],
-    strict: [
-      {
-        plugins: {
-          qwik: this,
-        },
-        rules: strictRules,
-      },
-    ],
+    get recommended() {
+      return recommendedConfig;
+    },
+    get strict() {
+      return strictConfig;
+    },
   },
   meta: {
     name: pkg.name,
@@ -89,4 +83,22 @@ const qwikEslint9Plugin = {
   rules,
 };
 
+const recommendedConfig: TSESLint.FlatConfig.ConfigArray = [
+  {
+    plugins: {
+      qwik: qwikEslint9Plugin,
+    },
+    rules: recommendedRulesLevels,
+  },
+];
+
+const strictConfig: TSESLint.FlatConfig.ConfigArray = [
+  {
+    plugins: {
+      qwik: qwikEslint9Plugin,
+    },
+    rules: strictRulesLevels,
+  },
+];
+
 export { configs, qwikEslint9Plugin, rules };

packages/eslint-plugin-qwik/package.json

@@ -11,10 +11,10 @@
   "devDependencies": {
     "@builder.io/qwik": "workspace:^",
     "@builder.io/qwik-city": "workspace:^",
+    "@types/eslint": "9.6.1",
     "@types/estree": "1.0.5",
     "@typescript-eslint/rule-tester": "8.14.0",
-    "redent": "4.0.0",
-    "@types/eslint": "9.6.1"
+    "redent": "4.0.0"
   },
   "engines": {
     "node": ">=16.8.0 <18.0.0 || >=18.11"