@guardian/eslint-config 9.0.0 → 10.0.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @guardian/eslint-config
 
+## 10.0.0-beta.0
+
+### Major Changes
+
+This is pre-release that requires [ESLint 9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/).
+
+It should be feature complete, but this release is to allow for feedback and testing.
+
+It replaces both `@guardian/eslint-config@9` and `@guardian/eslint-config-typescript@12` with a single package.
+
+It also includes configs for `jest`, `storybook` and `react`.
+
+See the [README](README.md) for full details.
+
+> ESLint 9 contains a lot of breaking changes, including a new config format. See their [migration guide](https://eslint.org/docs/latest/use/migrate-to-9.0.0) for more details.
+>
+> Note that [ESLint 8 is EOL 2024-10-05](https://eslint.org/version-support/).
+
 ## 9.0.0
 
 ### Major Changes

package/README.md

@@ -1,24 +1,108 @@
 # `@guardian/eslint-config`
 
-> ESLint config for Guardian JavaScript projects.
+> ESLint configs for Guardian JavaScript and TypeScript projects.
 
 ## Installation
 
 ```bash
-yarn add -D @guardian/eslint-config
-```
+npm install --save-dev @guardian/eslint-config
 
-or
+# or
+yarn add --dev @guardian/eslint-config
 
-```bash
-npm install --save-dev @guardian/eslint-config
+# or
+pnpm install --save-dev @guardian/eslint-config
 ```
 
 ## Usage
 
+#### Example
+
 ```js
-// ESLint configuration file
-{
-    "extends": "@guardian/eslint-config"
-}
+// eslint.config.js
+
+import guardian from '@guardian/eslint-config';
+
+export default [
+	...guardian.configs.recommended,
+	...guardian.configs.jest,
+	...guardian.configs.react,
+	...guardian.configs.storybook,
+];
 ```
+
+### Configs
+
+The package's default export is an object with a `configs` property that provides configs for different projects.
+
+Some of them are single-purpose, and others compose the single-purpose configs into useful presets.
+
+#### [`configs.recommended`](./configs/recommended.js)
+
+Provides a recommended collection of useful configs covering both JavaScript and TypeScript.
+
+Composes:
+
+- `configs.javascript`
+- `configs.typescript`
+- `configs.imports`
+- `configs.comments`
+
+#### [`configs.javascript`](./configs/javascript.js)
+
+_Included in `configs.recommended`._
+
+Provides a collection of configs for checking JavaScript, which are also applied to TypeScript files.
+
+It automatically detects your project type (using `package.json#type`), and uses an appropriate config for each file.
+
+Composes:
+
+- `configs.esm`
+- `configs.cjs`
+
+#### [`configs.esm`](./configs/esm.js)
+
+_Included in `configs.javascript`._
+
+Provides a collection of configs for ECMAScript modules.
+
+It assumes everything will be ECMAScript, and will error if you use it on a CommonJS module.
+
+#### [`configs.cjs`](./configs/cjs.js)
+
+_Included in `configs.javascript`._
+
+Provides a collection of configs for CommonJS modules.
+
+It assumes everything will be CommonJS, and will error if you use it on an ECMAScript module.
+
+#### [`configs.typescript`](./configs/typescript.js)
+
+_Included in `configs.recommended`._
+
+Provides a collection of configs for checking TypeScript.
+
+#### [`configs.imports`](./configs/imports.js)
+
+_Included in `configs.recommended`._
+
+Provides a collection of configs ensuring best practice around module imports and exports.
+
+#### [`configs.comments`](./configs/comments.js)
+
+_Included in `configs.recommended`._
+
+Provides a collection of configs ensuring best practice around code comments.
+
+#### [`configs.jest`](./configs/jest.js)
+
+Provides a collection of configs for checking Jest units tests.
+
+#### [`configs.react`](./configs/react.js)
+
+Provides a collection of configs for checking React components.
+
+#### [`configs.storybook`](./configs/storybook.js)
+
+Provides a collection of configs for checking Storybook stories.

package/configs/comments.js

@@ -0,0 +1,32 @@
+import { fixupPluginRules } from '@eslint/compat';
+import eslintComments from 'eslint-plugin-eslint-comments';
+
+export default [
+	{
+		name: '@guardian/comments',
+		plugins: {
+			'eslint-comments': fixupPluginRules(eslintComments),
+		},
+		rules: {
+			// require a `eslint-enable` comment for every `eslint-disable` comment
+			'eslint-comments/disable-enable-pair': [
+				'error',
+				{ allowWholeFile: true },
+			],
+
+			// disallow duplicate `eslint-disable` comments
+			'eslint-comments/no-duplicate-disable': 'error',
+
+			// disallow unused eslint-en/disable comments
+			// (make sure they're not left in after a fix)
+			'eslint-comments/no-unused-disable': 'error',
+			'eslint-comments/no-unused-enable': 'error',
+
+			// require an explanation if you disable eslint
+			'eslint-comments/require-description': [
+				'error',
+				{ ignore: ['eslint-enable'] },
+			],
+		},
+	},
+];

package/configs/imports.js

@@ -0,0 +1,80 @@
+// https://github.com/import-js/eslint-plugin-import/issues/2948#issuecomment-2119214365
+import importX from 'eslint-plugin-import-x';
+
+export default [
+	{
+		name: '@guardian/imports',
+		plugins: {
+			import: importX,
+		},
+		rules: {
+			// recommended defaults
+			'import/no-unresolved': 'error',
+			'import/named': 'error',
+			'import/namespace': 'error',
+			'import/default': 'error',
+			'import/export': 'error',
+
+			// encourages consistent token use across code bases
+			// (you have to deliberately rename an import) and
+			// makes the location of errors easier to discover:
+			// https://twitter.com/addyosmani/status/1411233253948747777
+			'import/no-default-export': 'error',
+			'import/prefer-default-export': 'off',
+
+			// less diff noise (they're hoisted anyway)
+			'import/first': 'error',
+
+			// fixable import formatting, designed to minimise diff noise
+			'sort-imports': [
+				'error',
+				{
+					ignoreCase: true,
+					ignoreDeclarationSort: true,
+					ignoreMemberSort: false,
+				},
+			],
+			'import/newline-after-import': 'error',
+			'import/order': [
+				'error',
+				{
+					groups: [
+						'builtin',
+						'external',
+						'internal',
+						'parent',
+						'sibling',
+						'index',
+						'object',
+						'unknown',
+					],
+					'newlines-between': 'never',
+					alphabetize: {
+						order: 'asc',
+						caseInsensitive: true,
+					},
+				},
+			],
+
+			// prevent circular dependencies
+			'import/no-cycle': ['error', { ignoreExternal: true }],
+		},
+	},
+	{
+		name: '@guardian/imports-default-exceptions',
+		files: [
+			'**/.lintstagedrc.*',
+			'**/astro.config.*',
+			'**/eslint.config.*',
+			'**/jest.config.*',
+			'**/rollup.config.*',
+			'**/svelte.config.*',
+			'**/*.stories.*',
+			'**/.storybook/main.*',
+		],
+		rules: {
+			'import/no-default-export': 'off',
+			'import/prefer-default-export': 'error',
+		},
+	},
+];

package/configs/javascript.base.js

@@ -0,0 +1,31 @@
+import js from '@eslint/js';
+import stylistic from '@stylistic/eslint-plugin';
+
+export default {
+	name: '@guardian/javascript',
+	plugins: {
+		'@stylistic': stylistic,
+	},
+	rules: {
+		...js.configs.recommended.rules,
+
+		// prevent dangling returns without braces
+		curly: ['error', 'all'],
+
+		// delimit members with semi-colons and require
+		// one at the end to keep diffs simpler
+		'@stylistic/member-delimiter-style': [
+			2,
+			{
+				multiline: {
+					delimiter: 'semi',
+					requireLast: true,
+				},
+				singleline: {
+					delimiter: 'semi',
+					requireLast: false,
+				},
+			},
+		],
+	},
+};

package/configs/javascript.cjs.js

@@ -0,0 +1,17 @@
+import globals from 'globals';
+import js from './javascript.base.js';
+
+export default {
+	...js,
+	name: '@guardian/cjs',
+	languageOptions: {
+		globals: {
+			...globals.commonjs,
+			...globals.node,
+		},
+		parserOptions: {
+			sourceType: 'commonjs',
+			ecmaVersion: 'latest',
+		},
+	},
+};

package/configs/javascript.esm.js

@@ -0,0 +1,17 @@
+import globals from 'globals';
+import js from './javascript.base.js';
+
+export default {
+	...js,
+	name: '@guardian/esm',
+	languageOptions: {
+		globals: {
+			...globals.browser,
+			...globals.nodeBuiltin,
+		},
+		parserOptions: {
+			sourceType: 'module',
+			ecmaVersion: 'latest',
+		},
+	},
+};

package/configs/javascript.js

@@ -0,0 +1,27 @@
+import { readPackageUp } from 'read-package-up';
+import cjs from './javascript.cjs.js';
+import esm from './javascript.esm.js';
+
+const isModule = (await readPackageUp()).packageJson.type === 'module';
+
+export default isModule
+	? [
+			{
+				files: ['**/*.{js,mjs,jsx,mjsx,ts,mts,tsx,mtsx}'],
+				...esm,
+			},
+			{
+				files: ['**/*.cjs', '**/*.cts'],
+				...cjs,
+			},
+		]
+	: [
+			{
+				files: ['**/*.{js,cjs,jsx,ts,cts,tsx}'],
+				...cjs,
+			},
+			{
+				files: ['**/*.{mjs,mjsx,mts,mtsx}'],
+				...esm,
+			},
+		];

package/configs/jest.js

@@ -0,0 +1,16 @@
+import globals from 'globals';
+
+export default [
+	{
+		name: '@guardian/jest',
+		files: [
+			'**/*.test.{js,mjs,cjs,jsx,mjsx,ts,mts,cts,tsx,mtsx}',
+			'**/*.spec.{js,mjs,cjs,jsx,mjsx,ts,mts,cts,tsx,mtsx}',
+		],
+		languageOptions: {
+			globals: {
+				...globals.jest,
+			},
+		},
+	},
+];

package/configs/react.js

@@ -0,0 +1,36 @@
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+import react from 'eslint-plugin-react';
+import globals from 'globals';
+
+export default [
+	{
+		name: '@guardian/react',
+		files: ['**/*.{jsx,mjsx,tsx,mtsx}'],
+		languageOptions: {
+			...react.configs.flat.recommended.languageOptions,
+			globals: {
+				...globals.serviceworker,
+				...globals.browser,
+			},
+		},
+		...react.configs.flat.recommended,
+		...react.configs.flat['jsx-runtime'],
+		plugins: {
+			react,
+			'jsx-a11y': jsxA11y,
+		},
+		rules: {
+			'react/no-unknown-property': [
+				'error',
+				{
+					ignore: ['css'],
+				},
+			],
+		},
+		settings: {
+			react: {
+				version: 'detect',
+			},
+		},
+	},
+];

package/configs/recommended.js

@@ -0,0 +1,16 @@
+import comments from './comments.js';
+import imports from './imports.js';
+import javascript from './javascript.js';
+import typescript from './typescript.js';
+
+export default [
+	...javascript,
+	...imports,
+	...typescript, // needs to come after `imports`
+	...comments,
+	{
+		linterOptions: {
+			reportUnusedDisableDirectives: 'error',
+		},
+	},
+];

package/configs/storybook.js

@@ -0,0 +1,8 @@
+// awaiting support https://github.com/storybookjs/eslint-plugin-storybook/issues/157
+
+export default [
+	{
+		name: '@guardian/storybook',
+		files: ['**/*.stories.{js,mjs,cjs,jsx,mjsx,ts,mts,cts,tsx,mtsx,mdx}'],
+	},
+];

package/configs/typescript.js

@@ -0,0 +1,122 @@
+// https://typescript-eslint.io/getting-started/
+
+import importX from 'eslint-plugin-import-x';
+// eslint-disable-next-line import/no-unresolved -- why can't this be resolved? literally no one knows
+import { config, configs } from 'typescript-eslint';
+
+export default config({
+	files: ['**/*.{ts,tsx,mtsx,mts,cts}'],
+	extends: [
+		...configs.recommended,
+		...configs.recommendedTypeChecked,
+		importX.configs.typescript,
+	],
+	languageOptions: {
+		parserOptions: {
+			projectService: true,
+		},
+	},
+	rules: {
+		// Performance boost, as TypeScript provides the same checks as part
+		// of standard type checking. See
+		// https://typescript-eslint.io/linting/troubleshooting/performance-troubleshooting/#eslint-plugin-import
+		'import/no-unresolved': 'off',
+		'import/named': 'off',
+		'import/namespace': 'off',
+		'import/default': 'off',
+
+		/*
+			FIXABLE STYLISTIC CHOICES THAT DIFFER FROM THE DEFAULT The intention
+			is to maximise clarity and consistency, not direct or inhibit what
+			can be done with code.
+			*/
+
+		// use `string[]` for simple arrays, `Array<string>` for complex
+		// ones
+		// https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/array-type.md#array-simple
+		'@typescript-eslint/array-type': [
+			'error',
+			{
+				default: 'array-simple',
+			},
+		],
+
+		// use `Record<string, unknown>` instead of `{ [key: string]:
+		// unknown }`
+		'@typescript-eslint/consistent-indexed-object-style': ['error', 'record'],
+
+		// be explicit when you only want to import a type: `import type {
+		// Foo } from 'Foo';`
+		'@typescript-eslint/consistent-type-imports': [
+			'error',
+			{
+				prefer: 'type-imports',
+			},
+		],
+
+		// use `(1 + foo.num!) == 'error'` instead of `1 + foo.num! ==
+		// 'error'`
+		'@typescript-eslint/no-confusing-non-null-assertion': 'error',
+
+		'@typescript-eslint/no-unnecessary-boolean-literal-compare': 'error',
+		'@typescript-eslint/no-unnecessary-condition': 'error',
+		'@typescript-eslint/no-unnecessary-qualifier': 'error',
+		'@typescript-eslint/no-unnecessary-type-arguments': 'error',
+		'@typescript-eslint/no-unused-vars': [
+			'error',
+			{
+				caughtErrors: 'none',
+			},
+		],
+
+		// use `str.includes(value)` instead of `str.indexOf(value) !== -1`
+		'@typescript-eslint/prefer-includes': 'error',
+
+		// https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/prefer-reduce-type-parameter.md
+		'@typescript-eslint/prefer-reduce-type-parameter': 'error',
+
+		// use String#startsWith or String#endsWith instead of
+		// String#indexOf et al
+		'@typescript-eslint/prefer-string-starts-ends-with': 'error',
+
+		// require explanation for changing compiler behaviour
+		'@typescript-eslint/ban-ts-comment': [
+			'error',
+			{
+				'ts-expect-error': 'allow-with-description',
+				'ts-ignore': true,
+				'ts-nocheck': true,
+				'ts-check': false,
+				minimumDescriptionLength: 3,
+			},
+		],
+
+		/* NOT FIXABLE BUT USEFUL */
+
+		// Enforce TypeScript naming conventions
+		// https://github.com/typescript-eslint/typescript-eslint/blob/master/packages/eslint-plugin/docs/rules/naming-convention.md
+		'@typescript-eslint/naming-convention': [
+			'error',
+
+			// types are 'PascalCase'
+			{
+				selector: ['typeLike', 'enumMember'],
+				format: ['PascalCase'],
+			},
+
+			// booleans are descriptive
+			// {
+			//  selector: 'variable', types: ['boolean'], format:
+			//  ['PascalCase'], prefix: ['is', 'should', 'has', 'can',
+			//  'did', 'will'],
+			// },
+		],
+
+		// use `foo ?? 'a string'` instead of `foo !== null && foo !==
+		// undefined ? foo : 'a string'`
+		'@typescript-eslint/prefer-nullish-coalescing': 'error',
+
+		// use `a?.b` instead of `a && a.b`
+		'@typescript-eslint/prefer-optional-chain': 'error',
+	},
+});

package/eslint.config.js

@@ -0,0 +1,14 @@
+import guardian from './index.js';
+
+export default [
+	...guardian.configs.recommended,
+	{
+		ignores: ['node_modules', '.wireit'],
+	},
+	{
+		files: ['index.js', 'configs/**'],
+		rules: {
+			'import/no-default-export': 'off',
+		},
+	},
+];

package/index.js

@@ -1,80 +1,25 @@
-module.exports = {
-	env: {
-		browser: true,
-		es6: true,
-		node: true,
-	},
-	extends: [
-		'eslint:recommended',
-		'plugin:import/errors',
-		'plugin:import/warnings',
-		'prettier',
-	],
-	plugins: ['eslint-comments'],
-	rules: {
-		// prevent dangling returns without braces
-		curly: ['error', 'all'],
-
-		// require a `eslint-enable` comment for every `eslint-disable` comment
-		'eslint-comments/disable-enable-pair': [2, { allowWholeFile: true }],
-
-		// disallow duplicate `eslint-disable` comments
-		'eslint-comments/no-duplicate-disable': 2,
-
-		// disallow unused eslint-en/disable comments
-		// (make sure they're not left in after a fix)
-		'eslint-comments/no-unused-disable': 2,
-		'eslint-comments/no-unused-enable': 2,
-
-		// require an explanation if you disable eslint
-		'eslint-comments/require-description': [2, { ignore: ['eslint-enable'] }],
-
-		// this doesn't catch bugs or make things more readable
-		// and sometimes tools or 3rd parties require it
-		'no-underscore-dangle': 0,
-
-		// encourages consistent token use across code bases
-		// (you have to deliberately rename an import) and
-		// makes the location of errors easier to discover:
-		// https://twitter.com/addyosmani/status/1411233253948747777
-		'import/no-default-export': 2,
-		'import/prefer-default-export': 0,
-
-		// less diff noise (they're hoisted anyway)
-		'import/first': 2,
-
-		// fixable import formatting, designed to minimise diff noise
-		'sort-imports': [
-			'error',
-			{
-				ignoreCase: true,
-				ignoreDeclarationSort: true,
-				ignoreMemberSort: false,
-			},
-		],
-		'import/newline-after-import': 2,
-		'import/order': [
-			'error',
-			{
-				groups: [
-					'builtin',
-					'external',
-					'internal',
-					'parent',
-					'sibling',
-					'index',
-					'object',
-					'unknown',
-				],
-				'newlines-between': 'never',
-				alphabetize: {
-					order: 'asc',
-					caseInsensitive: true,
-				},
-			},
-		],
-
-		// prevent circular dependencies
-		'import/no-cycle': ['error', { ignoreExternal: true }],
+import comments from './configs/comments.js';
+import imports from './configs/imports.js';
+import cjs from './configs/javascript.cjs.js';
+import esm from './configs/javascript.esm.js';
+import javascript from './configs/javascript.js';
+import jest from './configs/jest.js';
+import react from './configs/react.js';
+import recommended from './configs/recommended.js';
+import storybook from './configs/storybook.js';
+import typescript from './configs/typescript.js';
+
+export default {
+	configs: {
+		recommended,
+		javascript,
+		cjs,
+		esm,
+		typescript,
+		imports,
+		comments,
+		jest,
+		storybook,
+		react,
 	},
 };

package/package.json

@@ -1,28 +1,37 @@
 {
   "name": "@guardian/eslint-config",
-  "version": "9.0.0",
+  "version": "10.0.0-beta.0",
   "description": "ESLint config for Guardian JavaScript projects",
+  "type": "module",
   "main": "index.js",
   "dependencies": {
+    "@eslint/compat": "1.1.1",
+    "@eslint/js": "9.9.1",
+    "@stylistic/eslint-plugin": "2.6.4",
     "eslint-config-prettier": "9.1.0",
+    "eslint-import-resolver-typescript": "3.6.3",
     "eslint-plugin-eslint-comments": "3.2.0",
-    "eslint-plugin-import": "2.29.1"
+    "eslint-plugin-import-x": "4.0.0",
+    "eslint-plugin-jsx-a11y": "6.9.0",
+    "eslint-plugin-react": "7.35.0",
+    "eslint-plugin-react-hooks": "4.6.2",
+    "eslint-plugin-storybook": "0.8.0",
+    "globals": "15.9.0",
+    "read-package-up": "11.0.0",
+    "typescript-eslint": "8.3.0"
   },
   "devDependencies": {
-    "eslint": "8.57.0",
-    "tslib": "2.6.2",
+    "eslint": "9.9.0",
     "wireit": "0.14.4"
   },
   "peerDependencies": {
-    "eslint": "^8.57.0",
-    "tslib": "^2.6.2"
+    "eslint": "^9.9.0"
   },
   "wireit": {
     "lint": {
       "command": "eslint --cache --color .",
       "files": [
         "**",
-        "../../../.eslint*",
         "!.eslintcache"
       ],
       "output": []
@@ -32,30 +41,15 @@
       "clean": false,
       "files": [
         "**",
-        "../../../.eslint*",
         "!.eslintcache"
       ],
       "output": [
         "."
       ]
-    },
-    "tsc": {
-      "command": "tsc --pretty",
-      "files": [
-        "**",
-        "tsconfig.json",
-        "../tsconfig/tsconfig.json",
-        "../../../@types/**",
-        "../../../tsconfig.base.json",
-        "!(dist)/**",
-        "!.eslintcache"
-      ],
-      "output": []
     }
   },
   "scripts": {
     "fix": "wireit",
-    "lint": "wireit",
-    "tsc": "wireit"
+    "lint": "wireit"
   }
 }

package/.eslintrc.cjs

@@ -1,24 +0,0 @@
-module.exports = {
-	extends: ['../../../.eslintrc.cjs'],
-	ignorePatterns: [
-		'!**/*',
-		'node_modules',
-		'jest.dist.*', // depends on build output, so don't lint it
-		'.wireit',
-	],
-	overrides: [
-		{
-			files: ['*.ts', '*.tsx'],
-			parserOptions: {
-				tsconfigRootDir: __dirname,
-			},
-			rules: {},
-		},
-		{
-			files: ['**/*.test.*'],
-			env: {
-				jest: true,
-			},
-		},
-	],
-};

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-	"extends": "../../../tsconfig.base.json",
-	"include": ["**/*"],
-	"exclude": ["node_modules", ".wireit"]
-}