eslint.config.mjs

import base, { createConfig } from '@metamask/eslint-config';
import jest from '@metamask/eslint-config-jest';
import nodejs from '@metamask/eslint-config-nodejs';
import typescript from '@metamask/eslint-config-typescript';

const NODE_LTS_VERSION = 22;

/**
 * Arguments to the `no-restricted` syntax rule that advises use of
 * `${Controller}:stateChanged` instead of `:stateChange`.
 */
const NO_CONTROLLER_STATE_CHANGE_SELECTOR_OBJECTS = [
  {
    selector:
      'CallExpression[callee.property.name="subscribe"] > Literal[value=/^.+:stateChange$/]',
    message:
      "Subscribing to ':stateChange' events is deprecated. Use ':stateChanged' instead.",
  },
  {
    selector:
      'CallExpression[callee.property.name="delegate"] Property[key.name="events"] ArrayExpression > Literal[value=/^.+:stateChange$/]',
    message:
      "Delegating ':stateChange' events is deprecated. Use ':stateChanged' instead.",
  },
];

/**
 * Arguments to the `no-restricted-syntax` rule that prevents messsenger actions
 * from being called in constructors.
 */
const NO_MESSENGER_ACTIONS_IN_CONSTRUCTORS_SELECTOR_OBJECTS = [
  {
    selector:
      'MethodDefinition[kind="constructor"] CallExpression[callee.type="MemberExpression"][callee.property.name="call"][callee.object.type="MemberExpression"][callee.object.object.type="ThisExpression"][callee.object.property.name="messenger"]',
    message:
      'Do not call messenger actions in the constructor, as this forces clients to instantiate controllers or services in a specific order. Move this call to an init() method instead. Read the controller guidelines for more: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#do-not-call-messenger-actions-in-the-constructor',
  },
  {
    selector:
      'MethodDefinition[kind="constructor"] CallExpression[callee.type="MemberExpression"][callee.property.name="call"][callee.object.type="Identifier"][callee.object.name="messenger"]',
    message:
      'Do not call messenger actions in the constructor, as this forces clients to instantiate controllers or services in a specific order. Move this call to an init() method instead. Read the controller guidelines for more: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#do-not-call-messenger-actions-in-the-constructor',
  },
];

/**
 * Collects all options for a given array-valued rule across one or more flat
 * config arrays, excluding the leading severity element.
 *
 * ESLint flat config does not merge array-valued rules across config objects —
 * a later config silently replaces earlier ones. This helper makes it possible
 * to extend an upstream rule configuration rather than copy-pasting its options.
 *
 * @param {string} ruleName - The rule to collect options for.
 * @param {import('eslint').Linter.Config[][]} configs - Flat config arrays to
 * collect options from.
 * @returns {unknown[]} The options from all matching rule entries, with the
 * leading severity element omitted.
 */
function collectExistingRuleOptions(ruleName, configs) {
  return configs.flat().flatMap((config) => {
    const rule = config.rules?.[ruleName];
    if (!Array.isArray(rule)) {
      return [];
    }
    // Rule entries are ['error' | 'warn' | number, ...options].
    // Skip the first element (severity) and collect the rest.
    return rule.slice(1);
  });
}

const config = createConfig([
  ...base,
  {
    ignores: [
      '**/dist/**',
      '**/docs/**',
      '**/coverage/**',
      'merged-packages/**',
      '.yarn/**',
      'scripts/create-package/package-template/**',
    ],
  },
  {
    linterOptions: {
      reportUnusedDisableDirectives: 'error',
    },
  },
  {
    rules: {
      // Handled by Oxfmt.
      'prettier/prettier': 'off',
      'import-x/order': 'off',
    },
  },
  {
    rules: {
      // TODO: Re-enable this rule
      // Enabling it with error suppression breaks `--fix`, because the autofixer for this rule
      // does not work very well.
      'jsdoc/require-jsdoc': 'off',
    },
    settings: {
      jsdoc: {
        mode: 'typescript',
      },
    },
  },
  {
    files: [
      '**/*.{js,cjs,mjs}',
      '**/*.test.{js,ts}',
      '**/test/**/*.{js,ts}',
      '**/tests/**/*.{js,ts}',
      'scripts/*.ts',
      'scripts/create-package/**/*.ts',
    ],
    extends: [nodejs],
  },
  {
    files: ['**/*.{js,cjs}'],
    languageOptions: {
      sourceType: 'script',
      ecmaVersion: 2020,
    },
  },
  {
    files: ['**/*.ts'],
    extends: [typescript],
    languageOptions: {
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // TODO: Disable in `eslint-config-typescript`, tracked here: https://github.com/MetaMask/eslint-config/issues/413
      '@typescript-eslint/no-unnecessary-type-arguments': 'off',

      // This rule does not detect multiple imports of the same file where types
      // are being imported in one case and runtime values are being imported in
      // another
      'import-x/no-duplicates': 'off',

      // Enable rules that are disabled in `@metamask/eslint-config-typescript`
      '@typescript-eslint/no-explicit-any': 'error',

      // TODO: auto-fix breaks stuff
      '@typescript-eslint/promise-function-async': 'off',

      // TODO: Re-enable these rules
      // Enabling them with error suppression breaks `--fix`, because the autofixer for these rules
      // do not work very well.
      'jsdoc/check-tag-names': 'off',
      'jsdoc/require-jsdoc': 'off',

      // Add custom rule for deprecating `${Controller}:stateChange` in favor of
      // `:stateChanged`.
      'no-restricted-syntax': [
        'error',
        ...collectExistingRuleOptions('no-restricted-syntax', [
          base,
          typescript,
        ]),
        ...NO_CONTROLLER_STATE_CHANGE_SELECTOR_OBJECTS,
      ],
    },
  },
  {
    files: ['**/*.test.{js,ts}', '**/tests/**/*.{js,ts}'],
    extends: [jest],
    rules: {
      // TODO: Upgrade these from warning to error in shared config
      'jest/expect-expect': 'error',
      'jest/no-alias-methods': 'error',
      'jest/no-commented-out-tests': 'error',
      'jest/no-disabled-tests': 'error',
    },
    settings: {
      node: {
        version: `^${NODE_LTS_VERSION}`,
      },
    },
  },
  {
    // These files are test helpers, not tests. We still use the Jest ESLint
    // config here to ensure that ESLint expects a test-like environment, but
    // various rules meant just to apply to tests have been disabled.
    files: ['**/tests/**/*.{js,ts}'],
    ignores: ['**/*.test.{js,ts}'],
    rules: {
      'jest/no-export': 'off',
      'jest/require-top-level-describe': 'off',
      'jest/no-if': 'off',
    },
  },
  {
    files: ['tests/setupAfterEnv/matchers.ts'],
    languageOptions: {
      sourceType: 'script',
    },
  },
  // This should really be in `@metamask/eslint-config-typescript`
  {
    files: ['**/*.d.ts'],
    rules: {
      'import-x/unambiguous': 'off',
    },
  },
  {
    files: ['scripts/*.ts'],
    rules: {
      // Scripts may be self-executable and thus have hashbangs.
      'n/hashbang': 'off',
    },
  },
  {
    files: ['**/jest.environment.js'],
    rules: {
      // These files run under Node, and thus `require(...)` is expected.
      'n/global-require': 'off',
    },
  },
  {
    files: ['**/*.mjs'],
    languageOptions: {
      sourceType: 'module',
    },
  },
  // Prevent cross-package relative imports
  {
    files: ['packages/*/src/**/*.ts'],
    ignores: ['**/*.test.ts', '**/tests/**/*.ts'],
    rules: {
      'import-x/no-relative-packages': 'error',
    },
  },
  // Prevent calling messenger actions in controller/service constructors
  {
    files: ['packages/*/src/**/*.ts'],
    ignores: ['**/*.test.ts', '**/tests/**/*.ts'],
    rules: {
      'no-restricted-syntax': [
        'error',
        ...collectExistingRuleOptions('no-restricted-syntax', [
          base,
          typescript,
        ]),
        ...NO_CONTROLLER_STATE_CHANGE_SELECTOR_OBJECTS,
        ...NO_MESSENGER_ACTIONS_IN_CONSTRUCTORS_SELECTOR_OBJECTS,
      ],
    },
  },
  {
    // Prohibit exporting *AllowedActions, *AllowedEvents, and *MethodActions
    // from package index files
    files: ['packages/*/src/index.ts'],
    rules: {
      'no-restricted-syntax': [
        'error',
        ...collectExistingRuleOptions('no-restricted-syntax', [
          base,
          typescript,
        ]),
        ...NO_CONTROLLER_STATE_CHANGE_SELECTOR_OBJECTS,
        ...NO_MESSENGER_ACTIONS_IN_CONSTRUCTORS_SELECTOR_OBJECTS,
        {
          selector:
            'ExportNamedDeclaration > ExportSpecifier[local.name=/AllowedActions$/]',
          message:
            'Do not export AllowedActions types from package index files. These types describe external messenger dependencies and are obtainable from the packages that define them directly. Read the controller guidelines for more: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#define-but-do-not-export-a-type-union-for-external-action-types',
        },
        {
          selector:
            'ExportNamedDeclaration > ExportSpecifier[local.name=/AllowedEvents$/]',
          message:
            'Do not export AllowedEvents types from package index files. These types describe external messenger dependencies and are obtainable from the packages that define them directly. Read the controller guidelines for more: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#define-but-do-not-export-a-type-union-for-external-event-types',
        },
        {
          selector:
            'ExportNamedDeclaration > ExportSpecifier[local.name=/MethodActions$/]',
          message:
            'Do not export *MethodActions types from package index files. Internal messenger actions are already available via the *Actions type. Export the individual action types (along with *Actions) instead. Read the controller guidelines for more: https://github.com/MetaMask/core/blob/main/docs/code-guidelines/controller-guidelines.md#expose-controller-methods-through-messenger-in-bulk',
        },
      ],
    },
  },
  {
    files: ['packages/foundryup/**/*.{js,ts}'],
    rules: {
      'import-x/no-nodejs-modules': 'off',
      'n/no-unsupported-features/node-builtins': 'off',
      'n/no-missing-import': 'off',
      'n/no-restricted-import': 'off',
      'n/no-deprecated-api': 'off',
    },
  },
  {
    files: ['packages/messenger/src/generate-action-types/**/*.{js,ts}'],
    rules: {
      'import-x/no-nodejs-modules': 'off',
    },
  },
  {
    files: ['packages/messenger-cli/src/**/*.{js,ts}'],
    rules: {
      'import-x/no-nodejs-modules': 'off',
    },
  },
  {
    files: [
      'packages/notification-services-controller/src/NotificationServicesPushController/services/push/*-web.ts',
      'packages/notification-services-controller/src/NotificationServicesPushController/web/**/*.ts',
    ],
    rules: {
      // These files use `self` because they're written for a service worker context.
      // TODO: Move these files to the extension repository, `core` is just for platform-agnostic code.
      'consistent-this': 'off',
    },
  },
  {
    files: [
      'packages/assets-controllers/src/NftDetectionController.ts',
      'packages/assets-controllers/src/TokenRatesController.ts',
      'packages/assets-controllers/src/TokensController.ts',
      'packages/controller-utils/src/siwe.ts',
      'packages/ens-controller/src/EnsController.ts',
      'packages/gas-fee-controller/src/GasFeeController.ts',
      'packages/logging-controller/src/LoggingController.ts',
      'packages/message-manager/src/AbstractMessageManager.ts',
      'packages/message-manager/src/DecryptMessageManager.ts',
      'packages/message-manager/src/EncryptionPublicKeyManager.ts',
      'packages/permission-log-controller/src/PermissionLogController.ts',
      'packages/phishing-controller/src/PhishingController.ts',
      'packages/rate-limit-controller/src/RateLimitController.ts',
      'tests/fake-provider.ts',
      'tests/mock-network.ts',
    ],
    rules: {
      // TODO: Re-enable this rule
      // This has been temporarily disabled because the auto-fix mangles pre-existing JSDoc blocks
      // for types that don't follow TSDoc properly.
      // See https://github.com/gajus/eslint-plugin-jsdoc/issues/1054
      'jsdoc/check-tag-names': 'off',
    },
  },
]);

export default config;