feat!: migrate to ESLint 10 native flat config

.github/workflows/build-publish.yaml

@@ -51,14 +51,17 @@ jobs:
         with:
           install-modules: false
 
+      - name: 'Get package version 🔖'
+        id: 'get-package-version'
+        run: 'echo "version=v$(npm pkg get version | jq --raw-output)" >> "$GITHUB_OUTPUT"'
+
       - name: 'Publish to NPM 🚀'
         env:
           NODE_AUTH_TOKEN: '${{ secrets.NPM_AUTH_TOKEN }}'
+          # keep prereleases off the `latest` dist-tag
+          npm_config_tag: "${{ contains(steps.get-package-version.outputs.version, '-') && 'next' || 'latest' }}"
         uses: 'dudeofawesome/actions/npm-publish@a850bdff4354bdb891a86116f0378f8a890e2c16' # v1
 
-      - name: 'Get package version 🔖'
-        id: 'get-package-version'
-        run: 'echo "version=v$(npm pkg get version | jq --raw-output)" >> "$GITHUB_OUTPUT"'
       - name: 'Build jsonschema 🏗️'
         run: 'npm run build:jsonschema --workspace packages/code-style'
       - name: 'Publish files to Github Releases 🚀'

.gitignore

@@ -11,3 +11,4 @@ code-style-*-*.*.*.tgz
 
 # caches
 .eslintcache
+*.tsbuildinfo

.vscode/settings.json

@@ -46,13 +46,11 @@
     }
   ],
   "material-icon-theme.files.associations": {
-    "eslint-config*/*.yaml": "eslint",
     "styleint-config/*.yaml": "stylelint",
     "typescript-configs/**/*.json": "tsconfig",
     "javascript-configs/**/*.json": "jsconfig"
   },
   "yaml.schemas": {
-    "https://json.schemastore.org/eslintrc": ["eslint-config*/**/*.yaml"],
     "https://json.schemastore.org/stylelintrc.json": ["stylelint-config/*.yaml"]
   },
   "cSpell.words": ["esmodule"]

README.md

@@ -4,6 +4,10 @@
 
 See [create-configs](/packages/create-configs/README.md) for usage information.
 
+To add your own rules on top, see [docs/customizing-eslint.md](/docs/customizing-eslint.md).
+
+Upgrading from v2? See [docs/migrating-v2-to-v3.md](/docs/migrating-v2-to-v3.md).
+
 ## Contributing
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md)

code-style.code-workspace

@@ -73,13 +73,11 @@
       },
     ],
     "material-icon-theme.files.associations": {
-      "eslint-config*/*.yaml": "eslint",
       "styleint-config/*.yaml": "stylelint",
       "typescript-configs/**/*.json": "tsconfig",
       "javascript-configs/**/*.json": "jsconfig",
     },
     "yaml.schemas": {
-      "https://json.schemastore.org/eslintrc": ["eslint-config*/**/*.yaml"],
       "https://json.schemastore.org/stylelintrc.json": [
         "stylelint-config/*.yaml",
       ],

docs/customizing-eslint.md

@@ -0,0 +1,37 @@
+# Customizing the ESLint configs
+
+Add your own changes after the `@code-style` configs in your `eslint.config.mjs`. Later configs win.
+
+```js
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+import { config as base } from '@code-style/eslint-config';
+import { config as node } from '@code-style/eslint-config-node';
+import {
+  config as typescript,
+  files as typescript_files,
+} from '@code-style/eslint-config-typescript';
+
+export default defineConfig(
+  globalIgnores(['generated/']),
+  base,
+  node,
+  typescript,
+  {
+    rules: {
+      'max-lines': ['error', { max: 500 }],
+    },
+  },
+  {
+    files: typescript_files,
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+);
+```
+
+- **Scope changes to `@typescript-eslint/*` and `jest/*` rules with the config's `files`.** `@code-style/eslint-config-typescript` and `@code-style/eslint-config-jest` only load their plugins for the files they lint, so changing one of their rules for every file fails with `Could not find plugin`. Both packages export their `files`. Turning a rule `'off'` works without them.
+- **Setting only a severity keeps the rule's options, but setting options replaces all of them.** `'max-lines': 'warn'` keeps `max: 2000`, while `['error', { max: 500 }]` also drops `skipBlankLines` and `skipComments`, so restate any options you want to keep.
+- **Order matters.** Put each `/lenient` config right after the config it relaxes, and `@code-style/eslint-config-esmodule` after `@code-style/eslint-config-node`. [create-configs](../packages/create-configs/README.md) writes them in the right order.
+- **To find where a rule's setting comes from**, run `npx eslint --inspect-config`. Each config is named after its package (eg: `@code-style/eslint-config/rule-sets/footguns`).

docs/migrating-v2-to-v3.md

@@ -0,0 +1,32 @@
+# Migrating from v2 to v3
+
+v3 replaces the `.eslintrc` configs with [flat configs](https://eslint.org/docs/latest/use/configure/configuration-files) for **ESLint 10**, which requires Node `^20.19.0 || ^22.13.0 || >=24`.
+
+The easiest way to migrate is to re-run [create-configs](../packages/create-configs/README.md) with `overwrite` enabled. It replaces your `.eslintrc` & `.eslintignore` with an `eslint.config.mjs`, carrying over your rules, ignore patterns, and overrides' rules. It warns about any other settings (eg: `env`), which you'll need to add yourself.
+
+To migrate by hand:
+
+1. Replace your `.eslintrc.yaml` with an `eslint.config.mjs` that layers the same configs in the same order.
+
+    ```js
+    import { defineConfig } from 'eslint/config';
+
+    import { config as base } from '@code-style/eslint-config';
+    import { config as node } from '@code-style/eslint-config-node';
+    import { config as node_lenient } from '@code-style/eslint-config-node/lenient';
+
+    export default defineConfig(base, node, node_lenient);
+    ```
+
+1. Move any `.eslintignore` patterns into `globalIgnores([...])` from `eslint/config`.
+1. Install `eslint` as a dev dependency, and remove `@rushstack/eslint-patch`, `@types/eslint`, `eslint-plugin-import`, `@typescript-eslint/eslint-plugin`, and `@typescript-eslint/parser`.
+1. Remove `--ext` from your `eslint` scripts.
+
+`eslint-plugin-react` and `eslint-plugin-jsx-a11y` don't yet declare ESLint 10 support, so if you use `@code-style/eslint-config-react`, add the following to your `package.json`:
+
+```json
+"overrides": {
+  "eslint-plugin-react": { "eslint": "$eslint" },
+  "eslint-plugin-jsx-a11y": { "eslint": "$eslint" }
+}
+```

eslint.config.mjs

@@ -0,0 +1,29 @@
+import { defineConfig, globalIgnores } from 'eslint/config';
+
+import { config as base } from '@code-style/eslint-config';
+import { config as node } from '@code-style/eslint-config-node';
+import { config as cli } from '@code-style/eslint-config-cli';
+import { config as jest } from '@code-style/eslint-config-jest';
+import { config as typescript } from '@code-style/eslint-config-typescript';
+import { config as esmodule } from '@code-style/eslint-config-esmodule';
+
+export default defineConfig(
+  globalIgnores([
+    '.prettierrc.mjs',
+    '**/test/*/**',
+    // these packages lint themselves with their own eslint.config.mjs
+    'packages/code-style/',
+    'packages/create-configs/',
+    'packages/eslint-config/',
+    'packages/eslint-config-typescript/',
+    'packages/eslint-plugin-nest/',
+    'packages/jest-configs/',
+    'utils/',
+  ]),
+  base,
+  node,
+  cli,
+  jest,
+  typescript,
+  esmodule,
+);