eslint.config.mjs

import fs from 'node:fs';
import path from 'node:path';

import pluginEslintComments from '@eslint-community/eslint-plugin-eslint-comments';
import eslint from '@eslint/js';
import configPrettier from 'eslint-config-prettier';
import configTurbo from 'eslint-config-turbo/flat';
import pluginImport from 'eslint-plugin-import';
import pluginJsDoc from 'eslint-plugin-jsdoc';
import pluginJsxA11y from 'eslint-plugin-jsx-a11y';
import pluginPlaywright from 'eslint-plugin-playwright';
import pluginReact from 'eslint-plugin-react';
import pluginReactHooks from 'eslint-plugin-react-hooks';
import pluginStylex from '@stylexjs/eslint-plugin';
import pluginSimpleImportSort from 'eslint-plugin-simple-import-sort';
import pluginSonarjs from 'eslint-plugin-sonarjs';
import pluginTurbo from 'eslint-plugin-turbo';
import pluginUnusedImports from 'eslint-plugin-unused-imports';
import pluginYml from 'eslint-plugin-yml';
import globals from 'globals';
import tseslint from 'typescript-eslint';

import { CUSTOM_BLOCK_TAGS, CUSTOM_MODIFIER_TAGS } from './.typedoc/custom-tags.mjs';

const REPO_ROOT = import.meta.dirname;
const ECMA_VERSION = 2021,
  JAVASCRIPT_FILES = ['**/*.cjs', '**/*.js', '**/*.jsx', '**/*.mjs'],
  TEST_FILES = ['**/*.test.js', '**/*.test.jsx', '**/*.test.ts', '**/*.test.tsx', '**/test/**', '**/__tests__/**'],
  TYPESCRIPT_FILES = ['**/*.cts', '**/*.mts', '**/*.ts', '**/*.tsx'],
  // turbo lint runs `eslint src` from each package cwd; these must be repo-absolute
  IMPORT_RESOLVER_TSCONFIGS = [`${REPO_ROOT}/integration/tsconfig.json`],
  IMPORT_RESOLVER_TSCONFIG_NAMES = ['tsconfig.json', 'tsconfig.src.json', 'tsconfig.test.json', 'tsconfig.mosaic.json'];

// Each package must see only its own tsconfigs. Several packages define `@/*`, and a
// shared project list lets the resolver apply clerk-js's alias to UI or shared files.
const PACKAGE_IMPORT_RESOLVER_CONFIGS = fs
  .readdirSync(path.join(REPO_ROOT, 'packages'), { withFileTypes: true })
  .filter(entry => entry.isDirectory() && fs.existsSync(path.join(REPO_ROOT, 'packages', entry.name, 'package.json')))
  .flatMap(entry => {
    const project = IMPORT_RESOLVER_TSCONFIG_NAMES.map(name =>
      path.join(REPO_ROOT, 'packages', entry.name, name),
    ).filter(file => fs.existsSync(file));
    if (project.length === 0) {
      return [];
    }
    return [
      {
        name: `packages/${entry.name}/import-resolver`,
        files: [`packages/${entry.name}/**/*.{ts,tsx,js,jsx,mts,cts}`],
        settings: {
          'import/resolver': {
            node: true,
            typescript: {
              alwaysTryTypes: true,
              project,
            },
          },
        },
      },
    ];
  });

const noNavigateUseClerk = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow any usage of `navigate` from `useClerk()`',
      recommended: false,
    },
    messages: {
      noNavigate:
        'Usage of `navigate` from `useClerk()` is not allowed.\nUse `useRouter().navigate` to navigate in-between flows or `setActive({ redirectUrl })`.',
    },
    schema: [],
  },
  create(context) {
    const sourceCode = context.getSourceCode();

    return {
      // Case 1: Destructuring `navigate` from `useClerk()`
      VariableDeclarator(node) {
        if (
          node.id.type === 'ObjectPattern' && // Checks if it's an object destructuring
          node.init?.type === 'CallExpression' &&
          node.init.callee.name === 'useClerk'
        ) {
          for (const property of node.id.properties) {
            if (property.type === 'Property' && property.key.name === 'navigate') {
              context.report({
                node: property,
                messageId: 'noNavigate',
              });
            }
          }
        }
      },

      // Case 2 & 3: Accessing `navigate` on a variable or directly calling `useClerk().navigate`
      MemberExpression(node) {
        if (
          node.property.name === 'navigate' &&
          node.object.type === 'CallExpression' &&
          node.object.callee.name === 'useClerk'
        ) {
          // Case 3: Direct `useClerk().navigate`
          context.report({
            node,
            messageId: 'noNavigate',
          });
        } else if (node.property.name === 'navigate' && node.object.type === 'Identifier') {
          // Case 2: `clerk.navigate` where `clerk` is assigned `useClerk()`
          const scope = sourceCode.scopeManager.acquire(node);
          if (!scope) return;

          const variable = scope.variables.find(v => v.name === node.object.name);

          if (
            variable?.defs?.[0]?.node?.init?.type === 'CallExpression' &&
            variable.defs[0].node.init.callee.name === 'useClerk'
          ) {
            context.report({
              node,
              messageId: 'noNavigate',
            });
          }
        }
      },
    };
  },
};

const noGlobalObject = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow direct usage of `global.` - use `globalThis` instead for cross-platform compatibility',
      recommended: false,
    },
    messages: {
      noGlobal:
        'Use `globalThis` instead of `global` for cross-platform compatibility. The `global` object is Node.js-specific and may not exist in browser or other environments.',
    },
    schema: [],
  },
  create(context) {
    return {
      MemberExpression(node) {
        if (node.object.type === 'Identifier' && node.object.name === 'global') {
          context.report({
            node,
            messageId: 'noGlobal',
          });
        }
      },
    };
  },
};

const noUnstableMethods = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow methods or properties starting with `__unstable_`',
      recommended: false,
    },
    messages: {
      noUnstable:
        'Do not define methods or properties starting with `__unstable_`. For internal APIs, use `__internal_`, for experimental APIs, use `__experimental_`.',
    },
    schema: [],
  },
  create(context) {
    return {
      MemberExpression(node) {
        if (
          node.property.type === 'Identifier' &&
          typeof node.property.name === 'string' &&
          node.property.name.startsWith('__unstable_')
        ) {
          context.report({
            node: node.property,
            messageId: 'noUnstable',
          });
        }
      },
      Property(node) {
        if (
          node.key.type === 'Identifier' &&
          typeof node.key.name === 'string' &&
          node.key.name.startsWith('__unstable_')
        ) {
          context.report({
            node: node.key,
            messageId: 'noUnstable',
          });
        }
      },
      MethodDefinition(node) {
        if (
          node.key.type === 'Identifier' &&
          typeof node.key.name === 'string' &&
          node.key.name.startsWith('__unstable_')
        ) {
          context.report({
            node: node.key,
            messageId: 'noUnstable',
          });
        }
      },
    };
  },
};

const noRawInert = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow the raw `inert` JSX attribute',
      recommended: false,
    },
    messages: {
      useInertProps:
        "Use `{...inertProps(active)}` from '@clerk/shared/inert' instead of a raw `inert` attribute. React 18 and 19 need different `inert` values.",
    },
    schema: [],
  },
  create(context) {
    return {
      JSXAttribute(node) {
        if (node.name.type === 'JSXIdentifier' && node.name.name === 'inert') {
          context.report({ node, messageId: 'useInertProps' });
        }
      },
    };
  },
};

const noPhysicalCssProperties = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Enforce use of CSS logical properties instead of physical properties for RTL support',
      recommended: false,
    },
    messages: {
      useLogicalProperty:
        'Use logical CSS property "{{logical}}" instead of physical property "{{physical}}" for RTL support.',
      useLogicalTextAlign:
        'Use logical textAlign value "{{logical}}" instead of physical value "{{physical}}" for RTL support.',
    },
    schema: [],
  },
  create(context) {
    // Mapping of physical properties to logical equivalents
    const propertyMap = {
      left: 'insetInlineStart',
      right: 'insetInlineEnd',
      marginLeft: 'marginInlineStart',
      marginRight: 'marginInlineEnd',
      paddingLeft: 'paddingInlineStart',
      paddingRight: 'paddingInlineEnd',
      borderLeft: 'borderInlineStart',
      borderRight: 'borderInlineEnd',
      borderLeftWidth: 'borderInlineStartWidth',
      borderRightWidth: 'borderInlineEndWidth',
      borderLeftStyle: 'borderInlineStartStyle',
      borderRightStyle: 'borderInlineEndStyle',
      borderLeftColor: 'borderInlineStartColor',
      borderRightColor: 'borderInlineEndColor',
      borderTopLeftRadius: 'borderStartStartRadius',
      borderTopRightRadius: 'borderStartEndRadius',
      borderBottomLeftRadius: 'borderEndStartRadius',
      borderBottomRightRadius: 'borderEndEndRadius',
    };

    const checkProperty = (key, value) => {
      const keyName = key.type === 'Identifier' ? key.name : key.value;

      // Check for physical property names
      if (propertyMap[keyName]) {
        context.report({
          node: key,
          messageId: 'useLogicalProperty',
          data: {
            physical: keyName,
            logical: propertyMap[keyName],
          },
        });
      }

      // Check for textAlign with physical values
      if (keyName === 'textAlign' && value) {
        if (value.type === 'Literal' && (value.value === 'left' || value.value === 'right')) {
          const logicalValue = value.value === 'left' ? 'start' : 'end';
          context.report({
            node: value,
            messageId: 'useLogicalTextAlign',
            data: {
              physical: value.value,
              logical: logicalValue,
            },
          });
        }
      }
    };

    return {
      Property(node) {
        checkProperty(node.key, node.value);
      },
    };
  },
};

const noLeakedConditionalJsx = {
  selector: ":matches(JSXElement, JSXFragment) > JSXExpressionContainer > LogicalExpression[operator='&&']",
  message:
    'Use a ternary (`condition ? <Element /> : null`) for conditional JSX; `&&` renders a falsy left-hand value such as `0`.',
};

export default tseslint.config([
  {
    name: 'repo/ignores',
    ignores: [
      '.cache',
      '.idea',
      '.next',
      '.turbo',
      '.vscode',
      '!.*.js',
      '**/.turbo/*',
      '**/build/*',
      '**/coverage/*',
      '**/dist/*',
      '**/integration/templates/**/*',
      '**/node_modules/**',
      '*.snap',
      'commitlint.config.ts',
      'packages/*/dist/**',
      'packages/*/examples',
      'pnpm-lock.json',
      'eslint.config.mjs',
      'typedoc.config.mjs',
      'vitest.workspace.mjs',
      // package specific ignores
      'packages/astro/src/astro-components/**/*.ts',
      'packages/backend/src/runtime/**/*',
      'packages/clerk-js/rspack.config.js',
      'packages/shared/src/compiled/path-to-regexp/index.js',
      'packages/shared/tsdown.config.mjs',
      'packages/upgrade/src/__tests__/fixtures/**/*',
    ],
  },
  {
    name: 'repo/react-settings',
    settings: {
      react: {
        version: 'detect',
      },
    },
  },
  {
    name: 'repo/language-options',
    languageOptions: {
      ecmaVersion: ECMA_VERSION,
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
      sourceType: 'module',
    },
  },
  {
    name: 'repo/linter-options',
    linterOptions: {
      reportUnusedDisableDirectives: 'error',
    },
  },
  eslint.configs.recommended,
  tseslint.configs.recommendedTypeChecked,
  ...configTurbo,
  pluginImport.flatConfigs.recommended,
  pluginJsxA11y.flatConfigs.recommended,
  pluginReact.configs.flat.recommended,
  {
    name: 'repo/global',
    plugins: {
      'custom-rules': {
        rules: {
          'no-global-object': noGlobalObject,
          'no-navigate-useClerk': noNavigateUseClerk,
          'no-unstable-methods': noUnstableMethods,
          'no-physical-css-properties': noPhysicalCssProperties,
          'no-raw-inert': noRawInert,
        },
      },
      'simple-import-sort': pluginSimpleImportSort,
      'unused-imports': pluginUnusedImports,
      turbo: pluginTurbo,
    },
    settings: {
      'import/ignore': ['node_modules/react-native/index\\.js$'],
      'import/resolver': {
        node: true,
        typescript: {
          alwaysTryTypes: true,
          project: IMPORT_RESOLVER_TSCONFIGS,
        },
      },
    },
    rules: {
      'custom-rules/no-unstable-methods': 'error',
      'custom-rules/no-raw-inert': 'error',
      'no-label-var': 'error',
      'no-undef-init': 'warn',
      'no-restricted-imports': [
        'error',
        {
          paths: [
            {
              message: "Please always import from '@clerk/shared/<module>' instead of '@clerk/shared'.",
              name: '@clerk/shared',
            },
          ],
          patterns: [
            {
              group: ['!@clerk/shared/*'],
              message: 'ignore this line -- eslint matching workaround to allow all imports except @clerk/shared',
            },
            {
              group: ['@emotion/*'],
              message:
                'Please do not import emotion directly. Import helpers from ./design-system or ./primitives instead.',
            },
          ],
        },
      ],

      'jsx-a11y/no-onchange': 'off',

      'react/button-has-type': 'warn',
      'react/function-component-definition': 'off',
      'react/hook-use-state': 'warn',
      'react/jsx-boolean-value': 'warn',
      'react/jsx-curly-brace-presence': 'warn',
      'react/jsx-fragments': 'warn',
      'react/jsx-no-leaked-render': 'warn',
      'react/jsx-no-target-blank': [
        'error',
        {
          allowReferrer: true,
        },
      ],
      'react/jsx-no-useless-fragment': ['warn', { allowExpressions: true }],
      'react/jsx-pascal-case': 'warn',
      'react/jsx-sort-props': 'warn',
      'react/no-array-index-key': 'warn',
      'react/no-unstable-nested-components': 'warn',
      'react/no-unknown-property': ['error', { ignore: ['css'] }], // Emotion
      'react/self-closing-comp': 'warn',
      'react/prop-types': 'off',
      'react/react-in-jsx-scope': 'off',
      'simple-import-sort/imports': 'error',
      'sort-imports': 'off',
      ...pluginTurbo.configs['flat/recommended'].rules,
      'unused-imports/no-unused-imports': 'error',
      // TYPESCRIPT RULE DISABLES
      '@typescript-eslint/no-explicit-any': 'off',
      '@typescript-eslint/no-unsafe-argument': 'off',
      '@typescript-eslint/no-unsafe-assignment': 'off',
      '@typescript-eslint/no-unsafe-call': 'off',
      '@typescript-eslint/no-unsafe-declaration-merging': 'off',
      '@typescript-eslint/no-unsafe-member-access': 'off',
      '@typescript-eslint/no-unsafe-return': 'off',
      '@typescript-eslint/restrict-template-expressions': 'off',
    },
  },
  {
    name: 'repo/global-temporary',
    rules: {
      // TODO: All rules below should be set to their defaults
      // when we're able to make the appropriate changes.
      '@typescript-eslint/await-thenable': 'warn',
      '@typescript-eslint/ban-ts-comment': [
        `warn`,
        {
          'ts-ignore': 'allow-with-description',
          'ts-expect-error': 'allow-with-description',
          'ts-check': 'allow-with-description',
        },
      ],
      '@typescript-eslint/consistent-type-imports': [
        'error',
        {
          prefer: 'type-imports',
          disallowTypeAnnotations: true,
          fixStyle: 'separate-type-imports',
        },
      ],
      '@typescript-eslint/no-duplicate-type-constituents': 'off',
      '@typescript-eslint/no-floating-promises': [
        'warn',
        {
          ignoreVoid: true,
        },
      ],
      '@typescript-eslint/no-misused-promises': 'warn',
      '@typescript-eslint/no-redundant-type-constituents': 'warn',
      '@typescript-eslint/no-unnecessary-type-assertion': 'warn',
      '@typescript-eslint/no-unsafe-enum-comparison': 'warn',
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          args: 'after-used',
          argsIgnorePattern: '^_',
          ignoreRestSiblings: true,
          vars: 'all',
          varsIgnorePattern: '^_',
        },
      ],
      '@typescript-eslint/prefer-promise-reject-errors': 'warn',
      '@typescript-eslint/require-await': 'warn',

      // FIXME: This rule should be enabled when we're able to support import aliases
      'import/no-unresolved': ['error', { ignore: ['^#', '^~'] }],

      'jsx-a11y/alt-text': 'warn',
      'jsx-a11y/html-has-lang': 'warn',
      'jsx-a11y/no-autofocus': 'warn',

      'react/button-has-type': 'warn',
      'react/display-name': 'off',
      'react/jsx-curly-brace-presence': 'off',
      'react/jsx-no-leaked-render': 'off',
      'react/jsx-no-useless-fragment': 'warn',
      'react/jsx-sort-props': 'off',
    },
  },
  {
    name: 'repo/javascript',
    files: JAVASCRIPT_FILES,
    rules: {
      'no-unused-vars': [
        'error',
        {
          args: 'after-used',
          argsIgnorePattern: '^_',
          ignoreRestSiblings: true,
          vars: 'all',
          varsIgnorePattern: '^_',
        },
      ],
    },
  },
  {
    name: 'repo/typescript',
    files: TYPESCRIPT_FILES,
    extends: [pluginImport.flatConfigs.recommended, pluginImport.flatConfigs.typescript],
    rules: {
      'no-unused-vars': 'off',
      '@typescript-eslint/no-non-null-assertion': 'error',
    },
  },
  {
    name: 'repo/test',
    files: TEST_FILES,
    languageOptions: {
      globals: globals.vitest,
    },
    rules: {
      '@typescript-eslint/await-thenable': 'off',
      '@typescript-eslint/no-non-null-assertion': 'off',
      '@typescript-eslint/unbound-method': 'off',
    },
  },
  {
    name: 'repo/react-hooks',
    plugins: {
      'react-hooks': pluginReactHooks,
    },
    rules: {
      ...pluginReactHooks.configs.recommended.rules,
      'react-hooks/rules-of-hooks': 'warn',
    },
  },
  ...PACKAGE_IMPORT_RESOLVER_CONFIGS,
  {
    name: 'packages/clerk-js',
    files: ['packages/clerk-js/src/ui/**/*'],
    rules: {
      'custom-rules/no-navigate-useClerk': 'error',
      'custom-rules/no-unstable-methods': 'error',
    },
  },
  {
    name: 'packages/ui',
    files: ['packages/ui/src/**/*'],
    // Tests assert on style values they receive; they are not authoring styles.
    ignores: ['packages/ui/src/**/__tests__/**', 'packages/ui/src/**/*.test.{ts,tsx}'],
    rules: {
      'custom-rules/no-physical-css-properties': 'error',
      'custom-rules/no-navigate-useClerk': 'error',
      'custom-rules/no-unstable-methods': 'error',
    },
  },
  {
    name: 'packages/mosaic',
    files: ['packages/mosaic/src/**/*'],
    // Tests assert on style values they receive; they are not authoring styles.
    ignores: ['packages/mosaic/src/__tests__/**', 'packages/mosaic/src/**/*.test.{ts,tsx}'],
    plugins: {
      '@eslint-community/eslint-comments': pluginEslintComments,
      '@stylexjs': pluginStylex,
      sonarjs: pluginSonarjs,
    },
    rules: {
      '@eslint-community/eslint-comments/require-description': ['error', { ignore: ['eslint-enable'] }],
      'sonarjs/cognitive-complexity': ['error', 15],
      'sonarjs/no-collapsible-if': 'error',
      'sonarjs/no-identical-functions': 'error',
      'sonarjs/no-redundant-jump': 'error',
      'sonarjs/prefer-single-boolean-return': 'error',
      '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'never' }],
      '@typescript-eslint/switch-exhaustiveness-check': 'error',
      '@typescript-eslint/await-thenable': 'error',
      '@typescript-eslint/ban-ts-comment': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-misused-promises': 'error',
      '@typescript-eslint/no-unsafe-argument': 'error',
      '@typescript-eslint/no-unsafe-assignment': 'error',
      '@typescript-eslint/no-unsafe-call': 'error',
      '@typescript-eslint/no-unsafe-member-access': 'error',
      '@typescript-eslint/no-unsafe-return': 'error',
      '@typescript-eslint/only-throw-error': 'error',
      '@typescript-eslint/prefer-promise-reject-errors': 'error',
      '@typescript-eslint/use-unknown-in-catch-callback-variable': 'error',
      'react-hooks/exhaustive-deps': 'error',
      'react-hooks/rules-of-hooks': 'error',
      'max-lines': ['error', { max: 1000, skipBlankLines: true, skipComments: true }],
      'no-restricted-properties': [
        'error',
        { object: 'Reflect', property: 'get', message: 'Use typed property access or parse at the boundary.' },
        { object: 'Reflect', property: 'apply', message: 'Call the function directly.' },
      ],
      '@stylexjs/enforce-extension': 'error',
      '@stylexjs/no-legacy-contextual-styles': 'error',
      '@stylexjs/no-lookahead-selectors': 'error',
      '@stylexjs/no-nonstandard-styles': 'error',
      '@stylexjs/no-conflicting-props': 'error',
      '@stylexjs/no-unused': 'error',
      '@stylexjs/sort-keys': 'error',
      '@stylexjs/valid-shorthands': 'error',
      '@stylexjs/valid-styles': 'error',
      'no-restricted-syntax': [
        'error',
        {
          selector: "Property > Literal.key[value='&:hover']",
          message: "Use hover() from mosaic/utils instead of bare '&:hover'.",
        },
        noLeakedConditionalJsx,
        {
          selector: "Property > Literal.key[value='@media (hover: hover)']",
          message: "Use hover() from mosaic/utils instead of raw '@media (hover: hover)'.",
        },
        {
          selector: "Property > Literal.key[value='@media (prefers-reduced-motion: no-preference)']",
          message:
            "Use motionSafe() from mosaic/utils instead of raw '@media (prefers-reduced-motion: no-preference)'.",
        },
        // A Mosaic part takes `xstyle`, not `className`/`style`; its prop types already reject the pair,
        // this names the replacement. Native elements (lowercase) are unaffected.
        {
          selector:
            "JSXOpeningElement[name.type='JSXIdentifier'][name.name=/^[A-Z]/] > JSXAttribute[name.name=/^(className|style)$/]",
          message: 'Mosaic parts take `xstyle` (StyleX atoms) instead of `className`/`style`.',
        },
        {
          selector:
            "JSXOpeningElement[name.type='JSXMemberExpression'] > JSXAttribute[name.name=/^(className|style)$/]",
          message: 'Mosaic parts take `xstyle` (StyleX atoms) instead of `className`/`style`.',
        },
        // `{...stylex.props(x)}` is the same pair by another route; the types miss it because a
        // spread's optional keys skip excess-property checks.
        {
          selector:
            "JSXOpeningElement[name.type='JSXIdentifier'][name.name=/^[A-Z]/] > JSXSpreadAttribute > CallExpression[callee.object.name='stylex'][callee.property.name='props']",
          message: 'Mosaic parts take the atoms as `xstyle`, not a `stylex.props(...)` spread.',
        },
        {
          selector:
            "JSXOpeningElement[name.type='JSXMemberExpression'] > JSXSpreadAttribute > CallExpression[callee.object.name='stylex'][callee.property.name='props']",
          message: 'Mosaic parts take the atoms as `xstyle`, not a `stylex.props(...)` spread.',
        },
      ],
    },
  },
  {
    name: 'packages/mosaic/jsx-a11y',
    files: ['packages/mosaic/src/**/*'],
    rules: {
      // Mosaic renders elements through `render={p => <el {...p} />}`, so children and controls sit on
      // the outer component. Both rules only see the empty inner element and always report.
      'jsx-a11y/heading-has-content': 'off',
      'jsx-a11y/label-has-associated-control': 'off',
    },
  },
  {
    // StyleX `create()` files author conditions raw (`@media (hover: hover)`, `:hover`) — StyleX
    // is compile-time and cannot inline a `hover()`/`motionSafe()` helper imported into `create`,
    // so the media-query restrictions above (an Emotion-runtime convention) can't apply here. The
    // `@stylexjs/*` rules from the mosaic block still cover these files.
    name: 'packages/mosaic - stylex styles',
    files: ['packages/mosaic/src/**/*.styles.ts'],
    rules: {
      'no-restricted-syntax': 'off',
    },
  },
  {
    // Primitives are unstyled and take `className`/`style` like any other headless component; the
    // `xstyle`-only rule targets styled Mosaic parts and otherwise false-positives on things like
    // `<FloatingOverlay style={...}>`, a third-party component, not a Mosaic part.
    name: 'packages/mosaic - primitives',
    files: ['packages/mosaic/src/primitives/**/*'],
    ignores: ['packages/mosaic/src/**/*.test.{ts,tsx}'],
    rules: {
      'no-restricted-syntax': ['error', noLeakedConditionalJsx],
    },
  },
  {
    name: 'packages - vitest',
    files: ['packages/*/src/**/*.test.{ts,tsx}'],
    rules: {
      '@typescript-eslint/unbound-method': 'off',
      // vitest's `importOriginal<typeof import('...')>()` has no type-import equivalent.
      '@typescript-eslint/consistent-type-imports': [
        'error',
        { prefer: 'type-imports', disallowTypeAnnotations: false, fixStyle: 'separate-type-imports' },
      ],
    },
  },
  {
    name: 'packages - vitest type tests',
    files: ['packages/*/src/**/*.test-d.ts'],
    rules: {
      // Type tests bind values only to read their type back off with `typeof`.
      '@typescript-eslint/no-unused-vars': 'off',
    },
  },
  {
    name: 'packages/shared',
    files: ['packages/shared/src/**/*'],
    rules: {
      'custom-rules/no-global-object': 'error',
      'no-restricted-imports': [
        'error',
        {
          patterns: [
            {
              group: ['@clerk/shared', '@clerk/shared/*'],
              message:
                'Do not import from @clerk/shared package exports within the package itself. Use the @/ alias or relative imports from source files instead (e.g., import from "@/types" or "../../types").',
            },
            {
              group: ['../../../*'],
              message:
                'Relative imports should not traverse more than 2 levels up (../../). Use the @/ path alias instead (e.g., import from "@/types").',
            },
          ],
        },
      ],
    },
  },
  {
    name: 'packages/shared - tests',
    files: ['packages/shared/src/**/__tests__/**/*', 'packages/shared/src/**/*.test.{ts,tsx}'],
    rules: {
      // Allow `global.` in test files for mocking (e.g., global.window, global.console)
      'custom-rules/no-global-object': 'off',
    },
  },
  {
    name: 'packages/expo-passkeys',
    files: ['packages/expo-passkeys/src/**/*'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          patterns: ['node:*'],
        },
      ],
    },
  },
  {
    name: 'packages/nextjs',
    files: ['packages/nextjs/src/**/*'],
    rules: {
      'turbo/no-undeclared-env-vars': [
        'error',
        {
          allowList: ['_NEXT_ROUTER_BASEPATH'],
        },
      ],
    },
  },
  {
    name: 'packages/swingset',
    files: ['packages/swingset/src/**/*'],
    rules: {
      'turbo/no-undeclared-env-vars': [
        'error',
        {
          allowList: ['SWINGSET_DASHBOARD_URL'],
        },
      ],
    },
  },
  {
    name: 'packages/upgrade',
    files: ['packages/upgrade/src/**/*'],
    rules: {
      'custom-rules/no-unstable-methods': 'off',
      'react/no-unescaped-entities': 'off',
      '@typescript-eslint/no-floating-promises': 'warn',
    },
  },
  {
    name: 'repo/integration',
    ...pluginPlaywright.configs['flat/recommended'],
    files: ['integration/tests/**'],
    rules: {
      ...pluginPlaywright.configs['flat/recommended'].rules,
      'playwright/expect-expect': 'off',
      'playwright/no-skipped-test': 'off',
      'playwright/no-page-pause': 'warn',
    },
  },
  {
    name: 'repo/scripts',
    files: ['scripts/**/*'],
    rules: {
      'turbo/no-undeclared-env-vars': 'off',
    },
  },
  {
    name: 'repo/jsdoc',
    ...pluginJsDoc.configs['flat/recommended-typescript'],
    files: ['packages/shared/src/**/*.{ts,tsx}'],
    ignores: ['**/__tests__/**'],
    plugins: {
      jsdoc: pluginJsDoc,
    },
    rules: {
      ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
      'jsdoc/check-examples': 'off',
      'jsdoc/informative-docs': 'warn',
      'jsdoc/check-tag-names': [
        'warn',
        {
          // Derived from the Typedoc tooling's custom tags (`.typedoc/custom-tags.mjs`) so the two cannot drift.
          definedTags: [...CUSTOM_BLOCK_TAGS, ...CUSTOM_MODIFIER_TAGS].map(tag => tag.slice(1)),
          typed: false,
        },
      ],
      'jsdoc/require-hyphen-before-param-description': 'warn',
      'jsdoc/require-description': 'off',
      'jsdoc/require-description-complete-sentence': 'warn',
      'jsdoc/require-param': ['warn', { ignoreWhenAllParamsMissing: true }],
      'jsdoc/require-param-description': 'warn',
      'jsdoc/require-description-complete-sentence': 'off',
      'jsdoc/require-returns': 'off',
      'jsdoc/tag-lines': [
        'warn',
        'always',
        { count: 1, applyToEndTag: false, startLines: 1, tags: { param: { lines: 'never' } } },
      ],
    },
  },
  {
    name: 'repo/jsdoc-internal',
    files: ['packages/shared/src/**/internal/**/*.{ts,tsx}', 'packages/shared/src/**/*.{ts,tsx}'],
    plugins: {
      jsdoc: pluginJsDoc,
    },
    rules: {
      'jsdoc/require-jsdoc': 'off',
    },
  },
  ...pluginYml.configs['flat/recommended'],
  {
    name: 'eslint-prettier',
    rules: {
      ...configPrettier.rules,
      // eslint-config-prettier overrides
      curly: ['error', 'all'],
    },
  },
]);