eslint.config.mjs

import path from 'node:path';
import url from 'node:url';

import eslint from '@eslint/js';
import tsParser from '@typescript-eslint/parser';
import eslintPluginVitest from '@vitest/eslint-plugin';
import eslintConfig from 'eslint/config';
import eslintPluginJsdoc from 'eslint-plugin-jsdoc';
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
import eslintPluginSimpleImportSort from 'eslint-plugin-simple-import-sort';
import eslintPluginUnicorn from 'eslint-plugin-unicorn';
import globals from 'globals';
import tseslint from 'typescript-eslint';

import noArrayPushSpread from './.eslint/rules/performance/noArrayPushSpread.mjs';
import noArrayRebuildInLoop from './.eslint/rules/performance/noArrayRebuildInLoop.mjs';
import noArrayShiftMutationInLoop from './.eslint/rules/performance/noArrayShiftMutationInLoop.mjs';
import noNumberToLocaleString from './.eslint/rules/performance/noNumberToLocaleString.mjs';
import noFsPromisify from './.eslint/rules/style/noFsPromisify.mjs';
import noNodeSubpathImports from './.eslint/rules/style/noNodeSubpathImports.mjs';
import preferNodeDefaultImport from './.eslint/rules/style/preferNodeDefaultImport.mjs';

const __filename = url.fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default eslintConfig.defineConfig([
  {
    ignores: ['.*/**', 'dist/**', 'packages/*/deps/**', 'site/**'],
  },

  // @typescript-eslint
  eslint.configs.recommended,
  {
    files: ['**/*.{js,ts}'],
    extends: [tseslint.configs.strictTypeChecked, tseslint.configs.stylisticTypeChecked],
  },
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: __dirname,
      },
    },
    rules: {
      // Conflicts between @typescript-eslint plugins 😡
      '@typescript-eslint/non-nullable-type-assertion-style': 'off',

      // Personal preferences
      '@typescript-eslint/no-misused-promises': [
        'error',
        {
          // Allow passing async functions to places that don't explicitly accept them, such as
          // setTimeout()
          checksVoidReturn: false,
        },
      ],
      '@typescript-eslint/restrict-template-expressions': [
        'error',
        {
          allow: ['unknown'],
          allowNever: true,
        },
      ],
      '@typescript-eslint/unbound-method': 'error',
    },
  },
  {
    ignores: ['**/*.ts'],
    ...tseslint.configs.disableTypeChecked,
  },

  // Custom plugins
  {
    plugins: {
      local: {
        rules: {
          'no-fs-promisify': noFsPromisify,
          'no-node-subpath-imports': noNodeSubpathImports,
          'prefer-node-default-import': preferNodeDefaultImport,
          'no-array-push-spread': noArrayPushSpread,
          'no-array-rebuild-in-loop': noArrayRebuildInLoop,
          'no-array-shift-mutation-in-loop': noArrayShiftMutationInLoop,
          'no-number-to-locale-string': noNumberToLocaleString,
        },
      },
    },
    rules: {
      'local/no-fs-promisify': 'error',
      'local/no-node-subpath-imports': 'error',
      'local/prefer-node-default-import': 'error',
      'local/no-array-push-spread': 'error',
      'local/no-array-rebuild-in-loop': 'error',
      'local/no-array-shift-mutation-in-loop': 'error',
      'local/no-number-to-locale-string': 'error',
    },
  },

  // Third party configs
  eslintPluginUnicorn.configs.recommended,
  eslintPluginJsdoc.configs['flat/recommended-typescript-error'],
  {
    plugins: { vitest: eslintPluginVitest },
    rules: {
      ...eslintPluginVitest.configs.recommended.rules,
      'vitest/expect-expect': 'off',
      'vitest/no-unneeded-async-expect-function': 'off', // for Jest compatability for now
    },
    settings: {
      vitest: {
        typecheck: true,
      },
    },
  },
  {
    plugins: {
      'simple-import-sort': eslintPluginSimpleImportSort,
    },
    rules: {
      'simple-import-sort/exports': 'error',
      'simple-import-sort/imports': 'error',
    },
  },
  eslintPluginPrettierRecommended, // MUST BE THE LAST PLUGIN!

  // Language options
  {
    files: ['**/*.ts'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        projectService: true,
        tsconfigRootDir: __dirname,
      },
      sourceType: 'module',
      globals: {
        ...globals.builtin,
        ...eslintPluginVitest.environments.env.globals,
      },
    },
  },
  {
    files: ['**/*.mjs'],
    languageOptions: {
      globals: {
        ...globals.node,
      },
    },
  },

  // Rule overrides
  {
    // Rules for all JavaScript files
    rules: {
      // ***** Files *****
      'unicorn/filename-case': [
        'error',
        {
          case: 'camelCase',
          checkDirectories: false,
        },
      ],

      // ***** Imports *****
      'simple-import-sort/exports': 'error',
      'simple-import-sort/imports': 'error',

      // ***** JSDoc *****
      'jsdoc/require-jsdoc': [
        'error',
        {
          // Require on public parts of classes
          checkConstructors: false,

          contexts: [
            'ClassDeclaration',
            // TODO(cemmer): require private methods as well
            'MethodDefinition[accessibility!=private][key.name!=/^(get|set|with)[A-Z][a-zA-Z]+/]',
          ],
        },
      ],
      'jsdoc/require-param': 'off',
      'jsdoc/require-returns': 'off',
      'jsdoc/no-blank-blocks': 'error',

      // ***** Promises *****

      // ***** Functions *****

      // ***** Errors *****

      // ***** Operands *****
      eqeqeq: 'error',

      // ***** Conditionals *****

      // ***** Loops *****

      // ***** Objects *****

      // ***** Arrays *****

      // ***** Numbers *****

      // ***** Strings *****
      'prefer-template': 'error',

      // ********** Recommended Overrides **********

      // ***** unicorn:recommended *****
      // Superseded by other rules
      'unicorn/no-this-outside-of-class': 'off', // made safe by @typescript-eslint/unbound-method
      // Fixes
      'unicorn/prefer-single-call': [
        'error',
        {
          // Readable#push() doesn't have a rest parameter 😡
          ignore: ['readable.push'],
        },
      ],
      // Style and clarity preference differences
      'unicorn/consistent-class-member-order': 'off',
      'unicorn/consistent-function-scoping': ['error', { checkArrowFunctions: false }],
      'unicorn/import-style': 'off', // mostly overridden by noNodeSubpathImports.mjs
      'unicorn/max-nested-calls': 'off',
      'unicorn/no-array-reduce': 'off',
      'unicorn/no-await-expression-member': 'off',
      'unicorn/no-break-in-nested-loop': 'off', // unicorn/no-duplicate-loops + unicorn/prefer-continue encourage this
      'unicorn/no-hex-escape': 'off',
      'unicorn/no-unreadable-new-expression': 'off',
      'unicorn/no-useless-undefined': 'off',
      'unicorn/prefer-string-raw': 'off',
      'unicorn/prefer-switch': 'off',
      'unicorn/prefer-ternary': 'off',
      'unicorn/prefer-type-error': 'off',
      'unicorn/prevent-abbreviations': 'off',
      // Overly broad rules with too many false positives 😡
      'unicorn/no-unsafe-string-replacement': 'off', // doesn't curly braces in regex search
      'unicorn/prefer-await': 'off', // doesn't check if the call site is in an async context
      'unicorn/prefer-https': 'off', // comments can't be excluded
      'unicorn/prefer-iterator-to-array': 'off', // ArrayIterator#toArray() doesn't exist
      'unicorn/prefer-minimal-ternary': 'off', // lots of false positives, hurts readability

      // ***** ESLint:recommended *****
      // Referencing ASCII characters <32 is entirely legitimate
      'no-control-regex': 'off',
    },
  },
  {
    // Rules for TypeScript files
    files: ['**/*.ts'],
    rules: {
      // ***** Types *****

      // ***** Imports *****
      '@typescript-eslint/consistent-type-exports': 'error',
      '@typescript-eslint/consistent-type-imports': 'error',
      '@typescript-eslint/no-import-type-side-effects': 'error',

      // ***** Promises *****
      // Require any function or method that returns a Promise to be marked async.
      '@typescript-eslint/promise-function-async': ['error'],
      // Be even more strict than @typescript-eslint/strict-type-checked
      '@typescript-eslint/return-await': ['error', 'always'],

      // ***** Interfaces *****
      '@typescript-eslint/method-signature-style': 'error',

      // ***** Classes *****
      '@typescript-eslint/explicit-member-accessibility': ['error', { accessibility: 'no-public' }],
      '@typescript-eslint/prefer-readonly': 'error',
      // A lot of utility classes contain private functions that shouldn't be exposed
      '@typescript-eslint/no-extraneous-class': [
        'error',
        {
          allowStaticOnly: true,
        },
      ],
      // TODO(cemmer)
      '@typescript-eslint/no-misused-spread': 'off',

      // ***** Functions *****
      // Require explicit return types on functions and class methods.
      '@typescript-eslint/explicit-function-return-type': 'error',

      // ***** Conditionals *****
      // Don't allow unnecessary conditional checks, such as when a value is always true, which can also help catch cases
      // such as accidentally checking `if([]){}` vs. `if([].length){}`
      '@typescript-eslint/strict-boolean-expressions': [
        'error',
        {
          allowAny: true,
          allowNullableBoolean: true,
          allowNullableString: true,
        },
      ],

      // ***** Objects *****
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          /*** @ESLint/js defaults ***/
          vars: 'all',
          caughtErrors: 'all',
          reportUsedIgnorePattern: false,
          /*** Overrides ***/
          args: 'all',
          argsIgnorePattern: '^_',
          // Allow the use of destructuring to remove keys from an object
          ignoreRestSiblings: true,
        },
      ],

      // ********** Recommended Overrides **********

      // ***** plugin:@typescript-eslint/strict-type-checked *****
      // There are a few places where this needs to be allowed, but only a few, so warn on them
      '@typescript-eslint/no-floating-promises': 'warn',
      // There are a few places where this needs to be allowed, but only a few, so warn on them
      '@typescript-eslint/no-unused-expressions': 'warn',
      // TODO(cemmer): seems to conflict with Prettier with Array#reduce() calls
      '@typescript-eslint/no-unnecessary-type-arguments': 'off',
    },
  },

  {
    // These files have switch cases on enum values, and have defensive
    // programming in case it was written wrong
    files: [
      'src/factories/**/*.ts',
      'src/models/files/archives/**/*.ts',
      'src/models/patches/**/*.ts',
    ],
    rules: {
      '@typescript-eslint/no-unnecessary-condition': 'off',
    },
  },

  // Ignore JSDoc requirements for some files
  {
    files: ['test/**/*.ts', 'packages/*/test/**/*.ts'],
    rules: {
      'jsdoc/require-jsdoc': 'off',
    },
  },
]);