@foray1010/eslint-config 9.1.0 → 10.0.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.0.0](https://github.com/foray1010/common-presets/compare/@foray1010/eslint-config@9.2.0...@foray1010/eslint-config@10.0.0) (2023-03-23)
+
+### ⚠ BREAKING CHANGES
+
+- **eslint-config:** migrate to eslint flat config and mjs
+- require node `^16.14.0 || >=18.12.0`
+
+### Features
+
+- **eslint-config:** migrate to eslint flat config and mjs ([d435d01](https://github.com/foray1010/common-presets/commit/d435d012faf1574dda750917dbada56048eecd09))
+- support ES2021 ([40a0e28](https://github.com/foray1010/common-presets/commit/40a0e282c937825dfca1969c30ffc26e5bd2a27c))
+- **tsconfig:** split tsconfig to mutliple files for different scenarios ([fcaf3ae](https://github.com/foray1010/common-presets/commit/fcaf3aee3f9f1851439d01631c2e8584bde685ba))
+
+### Bug Fixes
+
+- **deps:** update dependency eslint-plugin-functional to v5 ([169a5c4](https://github.com/foray1010/common-presets/commit/169a5c4f7f7d10c6d2f5206e71942063f1b710cc))
+- **deps:** update dependency eslint-plugin-unicorn to v46 ([76621eb](https://github.com/foray1010/common-presets/commit/76621eb95fd7eb74fff3710ac739e4d12df1f768))
+- **eslint-config:** migrate eslint-plugin-eslint-comments to eslint-community version ([9a1ce64](https://github.com/foray1010/common-presets/commit/9a1ce646462cffd091d58fbbb39b0a83138f0f3b))
+
+### Miscellaneous Chores
+
+- require node `^16.14.0 || >=18.12.0` ([5baf6eb](https://github.com/foray1010/common-presets/commit/5baf6eba6d42958596c130724a502c59fe1a4e83))
+
+## [9.2.0](https://github.com/foray1010/common-presets/compare/@foray1010/eslint-config@9.1.0...@foray1010/eslint-config@9.2.0) (2023-02-25)
+
+### Features
+
+- **eslint-config:** avoid type imports with side effects ([ceda72a](https://github.com/foray1010/common-presets/commit/ceda72a42dab09540fe796cca7c88b82801f073d))
+
+### Bug Fixes
+
+- **deps:** update dependency eslint-plugin-jsdoc to v40 ([9d2a01e](https://github.com/foray1010/common-presets/commit/9d2a01e04880e21c2be8dd2e984ec5f01f28fcda))
+- **deps:** update dependency eslint-plugin-simple-import-sort to v10 ([5b258d7](https://github.com/foray1010/common-presets/commit/5b258d70b6c6f344645f983d6f7805edd2ee1908))
+- **deps:** update dependency eslint-plugin-simple-import-sort to v9 ([62d76f2](https://github.com/foray1010/common-presets/commit/62d76f2d2ef83ab5a909d3820a9f16acf387bbfa))
+
 ## [9.1.0](https://github.com/foray1010/common-presets/compare/@foray1010/eslint-config@9.0.1...@foray1010/eslint-config@9.1.0) (2022-12-21)
 
 ### Features

package/README.md

@@ -20,51 +20,95 @@ Z for looser rules
 
 1. `yarn add -DE @foray1010/eslint-config eslint prettier`
 
-1. Create an `.eslintrc.cjs` in the project root
-
-   For general purpose, support TypeScript
-
-   ```js
-   'use strict'
-
-   module.exports = {
-     root: true,
-     extends: ['@foray1010/eslint-config'],
-   }
-   ```
-
-   For frontend React projects, support TypeScript
-
-   ```js
-   'use strict'
-
-   module.exports = {
-     root: true,
-     extends: ['@foray1010/eslint-config/react'],
-   }
-   ```
-
-   For TS projects in monorepo, mark the `tsconfigRootDir` to use the correct `tsconfig.json`
-
-   ```js
-   'use strict'
-
-   module.exports = {
-     root: true,
-     extends: ['@foray1010/eslint-config'],
-     parserOptions: {
-       // Make sure the correct `tsconfig.json` is found in monorepo
-       tsconfigRootDir: __dirname,
-     },
-   }
-   ```
-
-1. Use default eslintignore via npm script
+1. Create an `eslint.config.mjs` in the project root (It is not a standard config path, but we opts for `.mjs` extension to make it compatible with commonjs projects)
+
+   - For general purpose or Node.js project (support TypeScript)
+
+     ```js
+     import {
+       eslintFilesConfig,
+       eslintIgnoresConfig,
+       eslintNodeConfig,
+     } from '@foray1010/eslint-config'
+
+     const config = [
+       ...eslintIgnoresConfig,
+       ...eslintFilesConfig,
+       ...eslintNodeConfig,
+     ]
+     export default config
+     ```
+
+   - For general frontend projects (support TypeScript)
+
+     ```js
+     import {
+       eslintFilesConfig,
+       eslintIgnoresConfig,
+       eslintBrowserConfig,
+     } from '@foray1010/eslint-config'
+
+     const config = [
+       ...eslintIgnoresConfig,
+       ...eslintFilesConfig,
+       ...eslintBrowserConfig,
+     ]
+     export default config
+     ```
+
+   - For frontend React projects (support TypeScript)
+
+     ```js
+     import {
+       eslintFilesConfig,
+       eslintIgnoresConfig,
+       eslintReactConfig,
+     } from '@foray1010/eslint-config'
+
+     const config = [
+       ...eslintIgnoresConfig,
+       ...eslintFilesConfig,
+       ...eslintReactConfig,
+     ]
+     export default config
+     ```
+
+   - You can apply config per different directories
+
+     ```js
+     import {
+       applyConfig,
+       eslintFilesConfig,
+       eslintIgnoresConfig,
+       eslintNodeConfig,
+       eslintReactConfig,
+     } from '@foray1010/eslint-config'
+
+     const config = [
+       ...eslintIgnoresConfig,
+       ...eslintFilesConfig,
+       ...applyConfig(
+         {
+           ignorePrefixes: ['src'],
+         },
+         eslintNodeConfig,
+       ),
+       ...applyConfig(
+         {
+           filePrefixes: ['src'],
+         },
+         eslintReactConfig,
+       ),
+     ]
+     export default config
+     ```
+
+1. Add npm script
 
    ```json
    {
      "scripts": {
-       "eslint": "eslint --ext=cjs,cts,js,mjs,mts,ts,tsx --ignore-path=node_modules/@foray1010/eslint-config/eslintignore"
+       "eslint": "ESLINT_USE_FLAT_CONFIG=true eslint --config eslint.config.mjs"
      }
    }
    ```

package/bases/base.mjs

@@ -0,0 +1,379 @@
+import js from '@eslint/js'
+import eslintPluginEslintComments from '@eslint-community/eslint-plugin-eslint-comments'
+// @ts-expect-error
+import { hasDep, isESM } from '@foray1010/common-presets-utils'
+import eslintPluginTypescriptEslint from '@typescript-eslint/eslint-plugin'
+import typescriptEslintParser from '@typescript-eslint/parser'
+import eslintPluginDeprecation from 'eslint-plugin-deprecation'
+import eslintPluginFunctional from 'eslint-plugin-functional'
+import eslintPluginImport from 'eslint-plugin-import'
+import eslintPluginJest from 'eslint-plugin-jest'
+import eslintPluginSimpleImportSort from 'eslint-plugin-simple-import-sort'
+import eslintPluginUnicorn from 'eslint-plugin-unicorn'
+import globals from 'globals'
+
+import { testFileGlobs, typeScriptFileGlobs } from '../constants.mjs'
+
+/** @type {import('eslint').Linter.FlatConfig} */
+const cjsConfig = {
+  languageOptions: {
+    globals: globals.commonjs,
+    sourceType: 'script',
+  },
+  rules: {
+    // commonjs must use strict mode
+    strict: ['error', 'global'],
+  },
+}
+
+/** @type {import('eslint').Linter.FlatConfig} */
+const esmConfig = {
+  languageOptions: {
+    sourceType: 'module',
+  },
+  plugins: {
+    'simple-import-sort': eslintPluginSimpleImportSort,
+  },
+  rules: {
+    // auto sort export statements
+    'simple-import-sort/exports': 'error',
+    // auto sort import statements
+    'simple-import-sort/imports': 'error',
+  },
+}
+
+/** @type {readonly import('eslint').Linter.FlatConfig[]} */
+const baseConfig = [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 2021,
+      globals: {
+        // should align with languageOptions.ecmaVersion
+        ...globals.es2021,
+        /* Not using `node` to explicitly import node.js only built-in modules, e.g.
+         * import { Buffer } from 'node:buffer'
+         * import process from 'node:process'
+         */
+        ...globals['shared-node-browser'],
+      },
+    },
+    plugins: {
+      '@eslint-community/eslint-comments': eslintPluginEslintComments,
+      import: eslintPluginImport,
+      unicorn: eslintPluginUnicorn,
+    },
+    rules: {
+      ...eslintPluginEslintComments.configs['recommended']?.rules,
+      ...eslintPluginImport.configs['recommended']?.rules,
+      // allow disable eslint rules for whole file without re-enable it in the end of the file
+      '@eslint-community/eslint-comments/disable-enable-pair': [
+        'error',
+        { allowWholeFile: true },
+      ],
+      // make sure every eslint-disable comments are in use
+      '@eslint-community/eslint-comments/no-unused-disable': 'error',
+      // always use named function for easier to debug via stack trace
+      'func-names': ['error', 'as-needed'],
+      // this rule doesn't support commonjs, some dependencies are using commonjs
+      'import/default': 'off',
+      // enforce extensions for both cjs and esm
+      'import/extensions': [
+        'error',
+        // https://nodejs.org/docs/latest-v14.x/api/esm.html#esm_mandatory_file_extensions
+        'always',
+        {
+          pattern: {
+            // eslint-plugin-import does not support checking es modules in typescript files
+            cts: 'never',
+            mts: 'never',
+            ts: 'never',
+            tsx: 'never',
+          },
+        },
+      ],
+      // make sure import statements above the others
+      'import/first': 'error',
+      // separate import statements from the others
+      'import/newline-after-import': 'error',
+      // avoid anonymous function or class for easier to debug via stack trace
+      // for other types, enforcing named data can improve autocomplete when importing
+      'import/no-anonymous-default-export': [
+        'error',
+        {
+          allowArray: false,
+          allowArrowFunction: false,
+          allowAnonymousClass: false,
+          allowAnonymousFunction: false,
+          allowCallExpression: false,
+          allowLiteral: false,
+          allowObject: false,
+        },
+      ],
+      // no circular dependency
+      'import/no-cycle': [
+        'error',
+        {
+          // speed up linting time
+          ignoreExternal: true,
+        },
+      ],
+      // do not allow import packages that are not listed in dependencies or peerDependencies
+      'import/no-extraneous-dependencies': [
+        'error',
+        {
+          devDependencies: [
+            '!**/src/**', // allow files outside of src/
+            '**/.*', // allow config rc files
+            ...testFileGlobs,
+          ],
+        },
+      ],
+      // forbid a module from importing itself
+      'import/no-self-import': 'error',
+      // use the shortest path in import statement, but allow /index because it will be standard to omit index as default file in directory
+      'import/no-useless-path-segments': [
+        'error',
+        {
+          commonjs: true,
+          noUselessIndex: false,
+        },
+      ],
+      // prefer explicitly convert type for readability
+      'no-implicit-coercion': 'error',
+      // make sure private class members are in-use
+      'no-unused-private-class-members': 'error',
+      // avoid assigning anonymous function to object key which is harder to trace when debug
+      'object-shorthand': ['error', 'always'],
+      // prefer `const` when the variable won't be reassigned
+      'prefer-const': [
+        'error',
+        {
+          // if one of the variables will be reassigned, do not enforce `const`
+          destructuring: 'all',
+        },
+      ],
+      // use with `unicorn/throw-new-error`
+      // disallow builtins to be created without `new` operator, to be consistent with es6 class syntax
+      'unicorn/new-for-builtins': 'error',
+      // prefer `import from 'node:xxx'`
+      'unicorn/prefer-node-protocol': 'error',
+      // prefer Number static properties over global ones
+      'unicorn/prefer-number-properties': 'error',
+      // use with `unicorn/new-for-builtins`
+      'unicorn/throw-new-error': 'error',
+    },
+  },
+  {
+    files: ['**/*.js'],
+    ...(isESM() ? esmConfig : cjsConfig),
+  },
+  {
+    files: ['**/*.cjs'],
+    ...cjsConfig,
+  },
+  {
+    files: ['**/*.mjs'],
+    ...esmConfig,
+  },
+  {
+    files: testFileGlobs,
+    languageOptions: {
+      globals: globals.jest,
+    },
+    plugins: {
+      jest: eslintPluginJest,
+    },
+    rules: {
+      ...eslintPluginJest.configs['recommended']?.rules,
+      ...eslintPluginJest.configs['style']?.rules,
+      // make sure lifecycle hooks on the top for readability
+      'jest/prefer-hooks-on-top': 'error',
+    },
+  },
+  // typescript plugins are depended on `typescript` package
+  // @ts-expect-error
+  ...(hasDep('typescript')
+    ? [
+        {
+          files: typeScriptFileGlobs,
+          languageOptions: {
+            /** @type {any} */
+            parser: typescriptEslintParser,
+            parserOptions: {
+              // faster linting on cli
+              // https://github.com/typescript-eslint/typescript-eslint/issues/3528
+              // turned off because @typescript-eslint/no-unsafe-* rules will output wrong errors
+              // allowAutomaticSingleRunInference: true,
+              project: ['./tsconfig*.json', './packages/*/tsconfig*.json'],
+            },
+          },
+          settings: {
+            'import/resolver': {
+              typescript: true,
+            },
+          },
+          plugins: {
+            '@typescript-eslint': eslintPluginTypescriptEslint,
+            deprecation: eslintPluginDeprecation,
+            functional: eslintPluginFunctional,
+          },
+          rules: {
+            ...eslintPluginTypescriptEslint.configs['eslint-recommended']
+              ?.rules,
+            ...eslintPluginTypescriptEslint.configs['recommended']?.rules,
+            ...eslintPluginTypescriptEslint.configs[
+              'recommended-requiring-type-checking'
+            ]?.rules,
+            ...eslintPluginImport.configs['typescript']?.rules,
+            // extend existing rule
+            '@typescript-eslint/ban-types': [
+              'error',
+              {
+                types: {
+                  // TypeScript team suggests to use `<T extends {}>` https://devblogs.microsoft.com/typescript/announcing-typescript-4-8/#unconstrained-generics-no-longer-assignable-to
+                  '{}': false,
+                },
+                extendDefaults: true,
+              },
+            ],
+            // separate type exports which allow certain optimizations within compilers
+            '@typescript-eslint/consistent-type-exports': 'error',
+            '@typescript-eslint/consistent-type-imports': [
+              'error',
+              {
+                // separate type imports which allow certain optimizations within compilers
+                prefer: 'type-imports',
+              },
+            ],
+            // disable the base rule as it can report incorrect errors, use @typescript-eslint/dot-notation instead
+            'dot-notation': 'off',
+            // only allow indexed syntax (e.g. `obj['key']`) for accessing undefined fields
+            '@typescript-eslint/dot-notation': [
+              'error',
+              {
+                allowIndexSignaturePropertyAccess: true,
+              },
+            ],
+            // encourage to use private accessibility modifier
+            '@typescript-eslint/explicit-member-accessibility': [
+              'error',
+              {
+                accessibility: 'explicit',
+              },
+            ],
+            // sometimes auto detect can provide a better and narrower type
+            '@typescript-eslint/explicit-module-boundary-types': 'off',
+            // disallow duplicated value in enum as it is error-prone
+            '@typescript-eslint/no-duplicate-enum-values': 'error',
+            // need empty function for react context default value
+            '@typescript-eslint/no-empty-function': 'off',
+            // encourage to check error type before use in catch clauses
+            '@typescript-eslint/no-implicit-any-catch': 'error',
+            // when using typescript 5.0 with verbatimModuleSyntax flag on, compiler will not remove import statements with only inline type imports which lead to side effects
+            '@typescript-eslint/no-import-type-side-effects': 'error',
+            // enforce correct usage of `void` type
+            '@typescript-eslint/no-invalid-void-type': 'error',
+            // allow using async function as event handler in frontend
+            '@typescript-eslint/no-misused-promises': [
+              'error',
+              { checksVoidReturn: false },
+            ],
+            // declaration merging between classes and interfaces is unsafe
+            '@typescript-eslint/no-unsafe-declaration-merging': 'error',
+            // do not block functions referring to other functions
+            '@typescript-eslint/no-use-before-define': [
+              'error',
+              {
+                /* options from eslint/no-use-before-define */
+                // allow use function before defined as they could be hoisted
+                functions: false,
+                classes: true,
+                variables: true,
+
+                /* options from @typescript-eslint/no-use-before-define */
+                enums: true,
+                // confusing option, it will disable `typedefs`
+                ignoreTypeReferences: false,
+                // tsc allows types to be used before define
+                typedefs: false,
+              },
+            ],
+            // use with functional/prefer-readonly-type
+            // mark class variables as readonly if it is not mutated
+            '@typescript-eslint/prefer-readonly': 'error',
+            // make sure functions which return a promise will just return a rejected promise instead of throwing an error
+            '@typescript-eslint/promise-function-async': 'error',
+            // allow primitive value in template string
+            '@typescript-eslint/restrict-template-expressions': [
+              'error',
+              {
+                allowNumber: true,
+                allowBoolean: true,
+                allowAny: true, // mistakenly recognize string as any in 4.29.3
+                allowNullish: true,
+                allowRegExp: true,
+              },
+            ],
+            // avoid missed switch-case by requiring switch-case statements to be exhaustive with union type
+            '@typescript-eslint/switch-exhaustiveness-check': 'error',
+            // ignore static function as those are not supposed to use `this`
+            '@typescript-eslint/unbound-method': [
+              'error',
+              { ignoreStatic: true },
+            ],
+            // do not allow usage of deprecated code
+            'deprecation/deprecation': 'error',
+            // use with @typescript-eslint/prefer-readonly
+            'functional/prefer-readonly-type': [
+              'error',
+              {
+                // sometimes it is easier to mutate, it should be fine to mutate within local scope
+                allowLocalMutation: true,
+                // don't force library consumer to use readonly type
+                allowMutableReturnType: true,
+                // allow mutating class variables
+                ignoreClass: 'fieldsOnly',
+              },
+            ],
+            // forbid unnecessary callback wrapper
+            'functional/prefer-tacit': 'error',
+            'no-restricted-syntax': [
+              'error',
+              {
+                // encourage to use JS standard #private over TS private accessibility modifier, but excluding constructor because it cannot be private in JS: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields#description
+                selector:
+                  ':matches(PropertyDefinition, MethodDefinition, TSParameterProperty)[accessibility="private"]:not([kind="constructor"])',
+                message:
+                  'Use #private instead (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields)',
+              },
+            ],
+            // @typescript-eslint/eslint-plugin suggests to disable it: https://github.com/typescript-eslint/typescript-eslint/blob/2588e9ea55f78352fdd6ae92a306135aabb49a1a/docs/linting/TROUBLESHOOTING.md#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
+            // It is disabled in recommended config but re-enabled here to enforce a subset of global variables that supported by both node.js and browsers
+            'no-undef': 'error',
+          },
+        },
+        {
+          files: typeScriptFileGlobs,
+          ignores: testFileGlobs.map((glob) => `!${glob}`),
+          plugins: {
+            '@typescript-eslint': eslintPluginTypescriptEslint,
+            jest: eslintPluginJest,
+          },
+          rules: {
+            // doesn't work with jest.fn<void>()
+            '@typescript-eslint/no-invalid-void-type': 'off',
+            // replace by jest/unbound-method
+            '@typescript-eslint/unbound-method': 'off',
+            // allow passing an unbound method to `expect` calls
+            'jest/unbound-method': ['error', { ignoreStatic: true }],
+          },
+        },
+        {
+          files: typeScriptFileGlobs,
+          ...esmConfig,
+        },
+      ]
+    : []),
+]
+export default baseConfig

package/bases/browser.mjs

@@ -0,0 +1,47 @@
+import restrictedGlobals from 'confusing-browser-globals'
+import eslintPluginCompat from 'eslint-plugin-compat'
+import eslintPluginImport from 'eslint-plugin-import'
+import eslintPluginJestDom from 'eslint-plugin-jest-dom'
+import eslintPluginTestingLibrary from 'eslint-plugin-testing-library'
+import globals from 'globals'
+
+import { testFileGlobs } from '../constants.mjs'
+
+/** @type {import('eslint').Linter.FlatConfig[]} */
+const browserConfig = [
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.webextensions,
+        // keep it until webpack has an official way to define env: https://github.com/webpack/webpack/issues/15833
+        // @ts-expect-error
+        process: 'readonly',
+      },
+    },
+    plugins: {
+      compat: eslintPluginCompat,
+      import: eslintPluginImport,
+    },
+    rules: {
+      'compat/compat': 'error',
+      // frontend environment doesn't support node.js modules
+      'import/no-nodejs-modules': 'error',
+      'no-restricted-globals': ['error', ...restrictedGlobals],
+    },
+  },
+  {
+    files: testFileGlobs,
+    plugins: {
+      'jest-dom': eslintPluginJestDom,
+      'testing-library': eslintPluginTestingLibrary,
+    },
+    rules: {
+      ...eslintPluginJestDom.configs['recommended']?.rules,
+      ...eslintPluginTestingLibrary.configs['dom']?.rules,
+      // allow to use nodejs modules in tests
+      'import/no-nodejs-modules': 'off',
+    },
+  },
+]
+export default browserConfig

package/bases/files.mjs

@@ -0,0 +1,8 @@
+/** @type {readonly import('eslint').Linter.FlatConfig[]} */
+const filesConfig = [
+  {
+    // replace `eslint --ext=cjs,cts,js,mjs,mts,ts,tsx` in legacy config
+    files: ['**/*.{cjs,cts,js,mjs,mts,ts,tsx}'],
+  },
+]
+export default filesConfig

package/bases/ignores.mjs

@@ -0,0 +1,14 @@
+/** @type {readonly import('eslint').Linter.FlatConfig[]} */
+const ignoresConfig = [
+  {
+    // replace `.eslintignore`
+    ignores: [
+      '**/.yarn/**',
+      '**/build/**',
+      '**/coverage/**',
+      '**/dist/**',
+      '**/node_modules/**',
+    ],
+  },
+]
+export default ignoresConfig