@prairielearn/eslint-config 0.0.1 → 1.1.0

package/src/configs/react.ts

@@ -0,0 +1,82 @@
+import eslintReact from '@eslint-react/eslint-plugin';
+import type { TSESLint } from '@typescript-eslint/utils';
+import jsxA11yX from 'eslint-plugin-jsx-a11y-x';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactYouMightNotNeedAnEffect from 'eslint-plugin-react-you-might-not-need-an-effect';
+
+// The eslint-react config has plugins/settings/rules but the type doesn't expose them all
+const eslintReactConfig = eslintReact.configs['recommended-typescript'] as {
+  plugins?: TSESLint.FlatConfig.Plugins;
+  rules?: TSESLint.FlatConfig.Rules;
+  settings?: TSESLint.FlatConfig.Settings;
+};
+
+/**
+ * React, React hooks, accessibility, and related rules.
+ */
+export function reactConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      plugins: {
+        'jsx-a11y-x': jsxA11yX,
+        'react-hooks': reactHooks,
+        'react-you-might-not-need-an-effect': reactYouMightNotNeedAnEffect,
+        ...eslintReactConfig.plugins,
+      },
+
+      rules: {
+        // React hooks
+        'react-hooks/exhaustive-deps': 'error',
+        'react-hooks/rules-of-hooks': 'error',
+
+        // react-you-might-not-need-an-effect rules as errors
+        ...Object.fromEntries(
+          Object.keys(reactYouMightNotNeedAnEffect.configs?.recommended?.rules ?? {}).map(
+            (ruleName: string) => [ruleName, 'error'],
+          ),
+        ),
+
+        // eslint-react recommended rules as errors
+        ...Object.fromEntries(
+          Object.entries(eslintReactConfig.rules ?? {}).map(
+            ([ruleName, severity]: [string, unknown]) => [
+              ruleName,
+              severity === 'off' ? 'off' : 'error',
+            ],
+          ),
+        ),
+        // We want to be able to use `useState` without the setter function for
+        // https://tkdodo.eu/blog/react-query-fa-qs#2-the-queryclient-is-not-stable
+        '@eslint-react/naming-convention/use-state': 'off',
+        // Forbid `snake_case` props.
+        '@eslint-react/no-forbidden-props': ['error', { forbid: ['/_/'] }],
+
+        // jsx-a11y strict rules
+        ...jsxA11yX.configs.strict.rules,
+        'jsx-a11y-x/anchor-ambiguous-text': 'error',
+        'jsx-a11y-x/lang': 'error',
+        'jsx-a11y-x/no-aria-hidden-on-focusable': 'error',
+        // Bootstrap turns some elements into interactive elements.
+        'jsx-a11y-x/no-noninteractive-element-to-interactive-role': [
+          'error',
+          {
+            li: ['menuitem', 'option', 'row', 'tab', 'treeitem'],
+            ol: ['listbox', 'menu', 'menubar', 'radiogroup', 'tablist', 'tree', 'treegrid'],
+            table: ['grid'],
+            td: ['gridcell'],
+            ul: ['listbox', 'menu', 'menubar', 'radiogroup', 'tablist', 'tree', 'treegrid', 'role'],
+          },
+        ],
+      },
+
+      settings: {
+        'jsx-a11y-x': {
+          attributes: {
+            for: ['htmlFor'],
+          },
+        },
+        ...eslintReactConfig.settings,
+      },
+    },
+  ];
+}

package/src/configs/stylistic.ts

@@ -0,0 +1,54 @@
+import stylistic from '@stylistic/eslint-plugin';
+import type { TSESLint } from '@typescript-eslint/utils';
+
+/**
+ * Stylistic formatting rules.
+ */
+export function stylisticConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      plugins: {
+        '@stylistic': stylistic,
+      },
+
+      rules: {
+        '@stylistic/jsx-curly-brace-presence': [
+          'error',
+          { children: 'never', propElementValues: 'always', props: 'never' },
+        ],
+
+        '@stylistic/jsx-self-closing-comp': [
+          'error',
+          {
+            component: true,
+            html: true,
+          },
+        ],
+        '@stylistic/jsx-tag-spacing': [
+          'error',
+          {
+            afterOpening: 'never',
+            beforeClosing: 'allow',
+            beforeSelfClosing: 'always',
+            closingSlash: 'never',
+          },
+        ],
+        '@stylistic/lines-between-class-members': [
+          'error',
+          'always',
+          { exceptAfterSingleLine: true },
+        ],
+        '@stylistic/no-tabs': 'error',
+        '@stylistic/padding-line-between-statements': [
+          'error',
+          { blankLine: 'always', next: 'function', prev: '*' },
+          { blankLine: 'always', next: '*', prev: 'import' },
+          { blankLine: 'any', next: 'import', prev: 'import' },
+        ],
+        // Blocks double-quote strings (unless a single quote is present in the
+        // string) and backticks (unless there is a tag or substitution in place).
+        '@stylistic/quotes': ['error', 'single', { avoidEscape: true }],
+      },
+    },
+  ];
+}

package/src/configs/tanstack.ts

@@ -0,0 +1,21 @@
+import pluginQuery from '@tanstack/eslint-plugin-query';
+import type { TSESLint } from '@typescript-eslint/utils';
+
+/**
+ * TanStack Query (React Query) rules.
+ */
+export function tanstackConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      plugins: {
+        '@tanstack/query': pluginQuery,
+      },
+
+      rules: {
+        // https://github.com/TanStack/query/blob/6402d756b702ac560b69a5ce84d6e4e764b96451/packages/eslint-plugin-query/src/index.ts#L43
+        ...pluginQuery.configs['flat/recommended'][0].rules,
+        '@tanstack/query/no-rest-destructuring': 'error',
+      },
+    },
+  ];
+}

package/src/configs/typescript.ts

@@ -0,0 +1,108 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+
+/**
+ * TypeScript-specific rules (non-type-aware).
+ */
+export function typescriptConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      rules: {
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { fixStyle: 'inline-type-imports' },
+        ],
+        // We use empty functions in quite a few places, so we'll disable this rule.
+        '@typescript-eslint/no-empty-function': 'off',
+        // Look, sometimes we just want to use `any`.
+        '@typescript-eslint/no-explicit-any': 'off',
+        // This was enabled when we upgraded to `@typescript-eslint/*` v6.
+        '@typescript-eslint/no-dynamic-delete': 'off',
+        // We use `!` to assert that a value is not `null` or `undefined`.
+        '@typescript-eslint/no-non-null-assertion': 'off',
+        // Replaces the standard `no-unused-vars` rule.
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          {
+            args: 'after-used',
+            argsIgnorePattern: '^_', // Args can be _
+            varsIgnorePattern: '^_.', // This includes lodash, which should be considered
+          },
+        ],
+      },
+    },
+  ];
+}
+
+/**
+ * Type-aware TypeScript rules.
+ * These require a tsconfig.json to be configured.
+ */
+export function typescriptTypeAwareRules(): TSESLint.FlatConfig.Rules {
+  return {
+    '@typescript-eslint/no-base-to-string': 'off',
+    '@typescript-eslint/no-invalid-void-type': [
+      'error',
+      {
+        allowAsThisParameter: true,
+      },
+    ],
+    '@typescript-eslint/no-unsafe-argument': 'off',
+    '@typescript-eslint/no-unsafe-assignment': 'off',
+    '@typescript-eslint/no-unsafe-call': 'off',
+    '@typescript-eslint/no-unsafe-member-access': 'off',
+    '@typescript-eslint/no-unsafe-return': 'off',
+    // Some functions are required to be async, but don't actually use any async code.
+    '@typescript-eslint/require-await': 'off',
+    // We don't always check that we got a error when a promise is rejected.
+    '@typescript-eslint/no-misused-promises': [
+      'error',
+      {
+        checksConditionals: true,
+        checksSpreads: true,
+        checksVoidReturn: {
+          // Common usage with `async` functions
+          arguments: false,
+          // Common usage with `async` onClick handlers
+          attributes: false,
+          inheritedMethods: true,
+          // Common usage with e.g. setState
+          properties: false,
+          returns: true,
+          variables: true,
+        },
+      },
+    ],
+    '@typescript-eslint/no-unnecessary-condition': [
+      'error',
+      { allowConstantLoopConditions: 'only-allowed-literals' },
+    ],
+    '@typescript-eslint/only-throw-error': [
+      'error',
+      {
+        allow: [
+          {
+            from: 'file',
+            name: 'HttpRedirect',
+          },
+        ],
+        allowRethrowing: true,
+        allowThrowingAny: true,
+        allowThrowingUnknown: true,
+      },
+    ],
+    '@typescript-eslint/prefer-nullish-coalescing': 'off',
+    '@typescript-eslint/prefer-promise-reject-errors': 'off',
+    '@typescript-eslint/prefer-regexp-exec': 'off',
+    '@typescript-eslint/restrict-template-expressions': [
+      'error',
+      {
+        allow: [{ from: 'lib', name: ['Error', 'URL', 'URLSearchParams'] }],
+        allowAny: true,
+        allowBoolean: true,
+        allowNullish: true,
+        allowNumber: true,
+        allowRegExp: true,
+      },
+    ],
+  };
+}

package/src/configs/unicorn.ts

@@ -0,0 +1,84 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+import eslintPluginUnicorn from 'eslint-plugin-unicorn';
+
+/**
+ * Unicorn plugin rules with PrairieLearn-specific overrides.
+ */
+export function unicornConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      plugins: {
+        unicorn: eslintPluginUnicorn,
+      },
+
+      rules: {
+        ...eslintPluginUnicorn.configs.recommended.rules,
+
+        // These rules don't align with our own style guidelines
+        'unicorn/filename-case': 'off', // We don't enforce specific styles for filenames
+        'unicorn/no-anonymous-default-export': 'off', // We use this for all of our pages
+        'unicorn/no-array-callback-reference': 'off',
+        'unicorn/no-array-method-this-argument': 'off',
+        'unicorn/no-array-reduce': 'off', // Sometimes, an array reduce is more readable
+        'unicorn/no-array-reverse': 'off', // `Array.prototype.toReversed` is not yet supported by our TypeScript config
+        'unicorn/no-array-sort': 'off', // Disabling for the time being to avoid unnecessary diffs
+        'unicorn/no-hex-escape': 'off',
+        'unicorn/no-lonely-if': 'off', // https://github.com/PrairieLearn/PrairieLearn/pull/12546#discussion_r2252261293
+        'unicorn/no-null': 'off',
+        'unicorn/no-useless-undefined': 'off', // Explicit undefined is more readable than implicit undefined
+        'unicorn/prefer-code-point': 'off',
+        'unicorn/prefer-dom-node-dataset': 'off', // https://github.com/PrairieLearn/PrairieLearn/pull/12546#discussion_r2261095992
+        'unicorn/prefer-export-from': 'off', // https://github.com/PrairieLearn/PrairieLearn/pull/12546#discussion_r2252265000
+        'unicorn/prefer-string-raw': 'off', // We don't use `String.raw` in our codebase
+        'unicorn/prefer-ternary': 'off', // if/else can be more readable than a ternary
+        'unicorn/prefer-top-level-await': 'off', // we use this on a lot of pages
+        'unicorn/prefer-type-error': 'off',
+        'unicorn/prevent-abbreviations': 'off',
+
+        // These rules have many violations. Decisions about enabling the rules have been deferred.
+        'unicorn/catch-error-name': 'off', // 200+ violations
+        'unicorn/no-array-for-each': 'off', // 300+ violations
+        'unicorn/no-await-expression-member': 'off', // 400+ violations
+        'unicorn/no-negated-condition': 'off', // 150+ violations
+        'unicorn/prefer-global-this': 'off', // 150+ violations
+        'unicorn/prefer-node-protocol': 'off', // 100+ violations
+        'unicorn/switch-case-braces': 'off', // 200+ violations
+
+        // TODO: investigate, < 100 violations
+        'unicorn/consistent-assert': 'off',
+        'unicorn/consistent-function-scoping': 'off',
+        'unicorn/escape-case': 'off',
+        'unicorn/import-style': 'off',
+        'unicorn/numeric-separators-style': 'off',
+        'unicorn/prefer-query-selector': 'off',
+        'unicorn/prefer-spread': 'off',
+        'unicorn/prefer-switch': 'off',
+        'unicorn/text-encoding-identifier-case': 'off',
+
+        // TODO: investigated and manual fixes are required
+        'unicorn/no-object-as-default-parameter': 'off',
+        'unicorn/prefer-add-event-listener': 'off',
+        'unicorn/prefer-dom-node-text-content': 'off',
+        'unicorn/prefer-event-target': 'off',
+
+        // False positives
+        'unicorn/error-message': 'off',
+        'unicorn/prefer-at': 'off', // https://github.com/microsoft/TypeScript/issues/47660#issuecomment-3146907649
+        'unicorn/throw-new-error': 'off',
+
+        // Duplicated from other lint rules
+        'unicorn/no-static-only-class': 'off',
+        'unicorn/no-this-assignment': 'off',
+        'unicorn/prefer-module': 'off',
+
+        // https://github.com/PrairieLearn/PrairieLearn/pull/12545/files#r2252069292
+        'unicorn/no-for-loop': 'off',
+
+        // Conflicts with prettier
+        'unicorn/no-nested-ternary': 'off',
+        'unicorn/number-literal-case': 'off',
+        'unicorn/template-indent': 'off',
+      },
+    },
+  ];
+}

package/src/configs/vitest.ts

@@ -0,0 +1,31 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+import vitest from '@vitest/eslint-plugin';
+
+/**
+ * Vitest test framework rules.
+ */
+export function vitestConfig(): TSESLint.FlatConfig.ConfigArray {
+  return [
+    {
+      plugins: {
+        vitest,
+      },
+
+      rules: {
+        // Use the recommended rules for vitest
+        ...vitest.configs.recommended.rules,
+
+        // We are disabling the test for a reason.
+        'vitest/no-disabled-tests': 'off',
+
+        // This gives a lot of false positives; we sometimes author tests that
+        // have the assertion in a helper function. We could refactor them in
+        // the future, but for now we'll disable this rule.
+        'vitest/expect-expect': 'off',
+
+        // We violate this rule in a lot of places. We'll turn it off for now.
+        'vitest/no-identical-title': 'off',
+      },
+    },
+  ];
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+import { globalIgnores } from 'eslint/config';
+import tseslint from 'typescript-eslint';
+
+import { baseConfig } from './configs/base.js';
+import { importsConfig } from './configs/imports.js';
+import { jsdocConfig } from './configs/jsdoc.js';
+import { lodashConfig } from './configs/lodash.js';
+import { perfectionistConfig } from './configs/perfectionist.js';
+import { type PrairieLearnPluginOptions, prairieLearnConfig } from './configs/prairielearn.js';
+import { reactConfig } from './configs/react.js';
+import { stylisticConfig } from './configs/stylistic.js';
+import { tanstackConfig } from './configs/tanstack.js';
+import { typescriptConfig, typescriptTypeAwareRules } from './configs/typescript.js';
+import { unicornConfig } from './configs/unicorn.js';
+import { vitestConfig } from './configs/vitest.js';
+
+export interface PrairieLearnEslintConfigOptions {
+  /**
+   * Root directory for TypeScript project service.
+   * Required for type-aware linting.
+   */
+  tsconfigRootDir: string;
+
+  /**
+   * Glob patterns for files to apply type-aware rules to.
+   * @default ['**\/*.{ts,tsx}']
+   */
+  typeAwareFiles?: string[];
+
+  /**
+   * Files to allow in defaultProject for type-aware linting.
+   * Useful for config files outside the main tsconfig.
+   * @default ['*.config.ts', '*.config.mts', 'vitest.config.ts']
+   */
+  allowDefaultProject?: string[];
+
+  /**
+   * Enable `@prairielearn/eslint-plugin` rules.
+   * @default true
+   */
+  prairielearn?: boolean;
+
+  /**
+   * Options for the `@prairielearn/eslint-plugin` rules.
+   */
+  prairieLearnOptions?: PrairieLearnPluginOptions;
+
+  /**
+   * Global ignores to apply.
+   * Will be merged with default ignores.
+   */
+  ignores?: string[];
+
+  /**
+   * Disable specific config modules.
+   */
+  disable?: {
+    react?: boolean;
+    vitest?: boolean;
+    perfectionist?: boolean;
+    unicorn?: boolean;
+    jsdoc?: boolean;
+    tanstack?: boolean;
+    lodash?: boolean;
+  };
+}
+
+/**
+ * Creates a PrairieLearn ESLint configuration array.
+ *
+ * @example
+ * ```js
+ * // eslint.config.mjs
+ * import { prairielearn } from '@prairielearn/eslint-config';
+ *
+ * export default [
+ *   ...prairielearn({
+ *     tsconfigRootDir: import.meta.dirname,
+ *   }),
+ *   // Add your project-specific rules here
+ * ];
+ * ```
+ */
+export function prairielearn(
+  options: PrairieLearnEslintConfigOptions,
+): TSESLint.FlatConfig.ConfigArray {
+  const {
+    tsconfigRootDir,
+    typeAwareFiles = ['**/*.{ts,tsx}'],
+    allowDefaultProject = ['*.config.ts', '*.config.mts', 'vitest.config.ts'],
+    prairielearn: enablePrairielearn = true,
+    prairieLearnOptions,
+    ignores = [],
+    disable = {},
+  } = options;
+
+  const jsFiles = ['**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}'];
+
+  const configs: TSESLint.FlatConfig.ConfigArray = [
+    // Base typescript-eslint configs (scoped to JS/TS files)
+    ...tseslint.config({
+      extends: [...tseslint.configs.stylistic, ...tseslint.configs.strict],
+      files: jsFiles,
+    }),
+    // Base configs (always included)
+    ...baseConfig(),
+    // TypeScript config (scoped to JS/TS files)
+    {
+      files: jsFiles,
+      ...typescriptConfig()[0],
+    },
+    ...importsConfig(),
+    ...stylisticConfig(),
+  ];
+
+  // Optional configs
+  if (!disable.react) {
+    configs.push(...reactConfig());
+  }
+
+  if (!disable.vitest) {
+    configs.push(...vitestConfig());
+  }
+
+  if (!disable.perfectionist) {
+    configs.push(...perfectionistConfig());
+  }
+
+  if (!disable.unicorn) {
+    configs.push(...unicornConfig());
+  }
+
+  if (!disable.jsdoc) {
+    configs.push(...jsdocConfig());
+  }
+
+  if (!disable.tanstack) {
+    configs.push(...tanstackConfig());
+  }
+
+  if (!disable.lodash) {
+    configs.push(...lodashConfig());
+  }
+
+  if (enablePrairielearn) {
+    configs.push(...prairieLearnConfig(prairieLearnOptions));
+  }
+
+  // Type-aware rules (applied to specified files)
+  // We use tseslint.config() to properly handle the extends syntax
+  configs.push(
+    ...tseslint.config({
+      extends: [
+        tseslint.configs.recommendedTypeCheckedOnly,
+        tseslint.configs.stylisticTypeCheckedOnly,
+      ],
+      files: typeAwareFiles,
+      languageOptions: {
+        parserOptions: {
+          projectService: {
+            allowDefaultProject,
+          },
+          tsconfigRootDir,
+        },
+      },
+      rules: typescriptTypeAwareRules(),
+    }),
+  );
+
+  // Default ignores
+  return [
+    ...configs,
+    globalIgnores(['.yarn/*', 'node_modules/*', 'dist/*', 'coverage/*', ...ignores]),
+  ];
+}
+
+// Re-export individual configs for advanced use
+export { baseConfig } from './configs/base.js';
+export { importsConfig } from './configs/imports.js';
+export { jsdocConfig } from './configs/jsdoc.js';
+export { lodashConfig } from './configs/lodash.js';
+export { perfectionistConfig } from './configs/perfectionist.js';
+export { prairieLearnConfig, type PrairieLearnPluginOptions } from './configs/prairielearn.js';
+export { reactConfig } from './configs/react.js';
+export { stylisticConfig } from './configs/stylistic.js';
+export { tanstackConfig } from './configs/tanstack.js';
+export { typescriptConfig, typescriptTypeAwareRules } from './configs/typescript.js';
+export { unicornConfig } from './configs/unicorn.js';
+export { vitestConfig } from './configs/vitest.js';

package/src/types.d.ts

@@ -0,0 +1,6 @@
+// Type declarations for ESLint plugins that don't provide their own types
+
+declare module 'eslint-plugin-no-floating-promise';
+declare module 'eslint-plugin-jsx-a11y-x';
+declare module 'eslint-plugin-you-dont-need-lodash-underscore';
+declare module 'eslint-plugin-react-you-might-not-need-an-effect';

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}