@gitlab/eslint-plugin 21.4.1 → 22.0.0

package/CHANGELOG.md

@@ -1,5 +1,228 @@
 # @gitlab/eslint-plugin
 
+## 22.0.0
+
+### Major Changes
+
+- 5c9ebc5: Migrate to ESLint 9 flat config.
+
+  Every config this package exports is now an array of flat config objects, meant to be spread into
+  an `eslint.config.js`. The eslintrc configs have been removed. `docs/usage.md` has the new examples
+  and a table mapping each old `extends` entry to its replacement.
+
+  ```js
+  const gitlab = require('@gitlab/eslint-plugin');
+
+  module.exports = [...gitlab.configs.default];
+  ```
+
+  ## If you use the `typescript` config, read this first
+
+  **Your `.ts` files were not being parsed as TypeScript before this release, and now they are.**
+  `lib/configs/typescript.js` set `parserOptions.parser: '@typescript-eslint/parser'` inside an
+  `overrides` block, and eslintrc ignores that key — only a `parser` key selects a parser. The flat
+  config sets `languageOptions.parser`, correctly. So `.ts` files are now genuinely parsed as
+  TypeScript, the type-aware rules in the config (`@typescript-eslint/no-floating-promises`,
+  `@typescript-eslint/return-await`, the `strict` preset) start doing real work for the first time,
+  and you should expect a wave of new findings on code that has not changed. Budget for that before
+  you upgrade. Nothing in the rule configuration changed to cause it; the rules were always listed,
+  they just had nothing to analyse.
+
+  Relatedly, the `typescript` config could not be installed from a clean install: it needs
+  `typescript` and `@typescript-eslint/parser` to load `@typescript-eslint/eslint-plugin`, and neither
+  was declared, so it only worked because the README told you to install them yourself. All three are
+  now declared optional peer dependencies. Install them in your own project and your package manager
+  will resolve them:
+
+  ```bash
+  yarn add --dev typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin
+  ```
+
+  The `overrides` block the README used to ask for is no longer needed and can be deleted.
+
+  ## Breaking changes
+
+  ### Config format and surface
+
+  1. **The seven eslintrc configs are gone.** Every `extends: ['plugin:@gitlab/*']` in an `.eslintrc`
+     stops resolving. Move to `eslint.config.js` and spread the array of the same name:
+     `...gitlab.configs.default`, `...gitlab.configs.vue`, and so on.
+  2. **The eight `base` fragments are no longer exported as configs** — `best-practices`, `errors`,
+     `es6`, `imports`, `node`, `strict`, `style` and `variables`. This is separate from the point
+     above: it hits anyone who extended a fragment directly rather than extending `base`. The files
+     are still in the package; only the public config surface shrinks. Use `base`.
+  3. **Config values changed shape.** Each config is now an array of flat config objects, not a single
+     eslintrc object. Code that read `configs.base.rules` or merged a config into another object needs
+     to work with the array instead.
+  4. **`configs` entries are lazy getters.** This keeps `require('@gitlab/eslint-plugin')` from
+     loading the optional TypeScript packages for consumers who do not use them. `Object.keys` and
+     `for...in` still list all seven names, but anything that _reads_ every entry at once —
+     `{ ...plugin.configs }`, a deep clone, `JSON.stringify` — invokes all seven getters and throws if
+     the TypeScript packages are absent. `Object.getOwnPropertyDescriptor(configs, name).value` is now
+     `undefined` where it used to be the config. Read configs by name.
+  5. **Deep subpath imports no longer resolve.** The package has no `exports` map, so every path in
+     the tarball used to be importable. The files behind those paths were deleted, so
+     `@gitlab/eslint-plugin/lib/configs/vue` and `@gitlab/eslint-plugin/eslint9/configs/base` now
+     throw `MODULE_NOT_FOUND`. Import from the package root. The `/eslint9` subpath itself still
+     resolves.
+  6. **`@gitlab/eslint-plugin/eslint9` is now the full package root**, not
+     `{ configs: { base, typescript } }`. It re-exports everything the root does, so existing imports
+     keep working, and it is deprecated — switch to `@gitlab/eslint-plugin`. It is scheduled for
+     removal in a future major release.
+  7. **`plugin.meta` now exists** (`{ name, version }`). Additive, and it is what makes the plugin
+     registerable in a flat config; ESLint uses it for cache keys and error attribution.
+
+  ### Requirements and dependencies
+
+  - **`eslint` is now a `^9.0.0` peer dependency.** ESLint 8 is no longer supported.
+  - **`engines.node` is now `^20.12.0 || ^22.0.0 || >=24.0.0`.** This drops Node 18 and the
+    odd-numbered lines. It is the intersection of every runtime dependency's own `engines`,
+    and is set by `eslint-plugin-jest` 29 rather than by ESLint 9, which is more permissive
+    (`^18.18.0 || ^20.9.0 || >=21.1.0`).
+  - **`@typescript-eslint/eslint-plugin`, `@typescript-eslint/parser` and `typescript` moved from
+    dependencies to optional peer dependencies.** Only consumers of the `typescript` config need them,
+    and those consumers now control the versions. See the section above.
+  - **`eslint-plugin-vue` is bumped to `^10.0.0`.** `vue/component-tags-order` was removed upstream
+    and is configured here as `vue/block-order` with the same options. If your project overrides
+    `vue/component-tags-order`, rename it: configuring a rule a plugin no longer defines is a hard
+    error in flat config, so ESLint refuses to run rather than ignoring it.
+  - **`vue-eslint-parser` is bumped to `^10.3.0`, `eslint-plugin-jest` to `^29.0.0`, and
+    `eslint-config-prettier` to `^10.0.0`.** Each brings its own upstream preset changes.
+  - **`@typescript-eslint/no-throw-literal` is configured as `@typescript-eslint/only-throw-error`**,
+    following the rename in `@typescript-eslint` v8.
+
+  ### ESLint 9 defaults
+
+  Two core rules report less than they did under ESLint 8:
+
+  - `no-constant-condition` no longer reports `while (true)`.
+  - `no-inner-declarations` no longer reports block-scoped function declarations.
+
+  `no-fallthrough`, `no-useless-escape` and `no-unused-expressions` gained new options in ESLint 9,
+  but their defaults preserve ESLint 8 behaviour, so nothing changes for them unless you opt in.
+
+  One flat-config default reports **more**. ESLint 9 defaults
+  `linterOptions.reportUnusedDisableDirectives` to `warn`, where eslintrc left unused directives
+  unreported unless you passed `--report-unused-disable-directives`. Every stale
+  `// eslint-disable` comment in your project — including ones made stale by the rule changes listed
+  below — now produces a warning. This is ESLint's default and not something this package sets, but
+  it is a new source of warnings on unchanged code, and it will fail a build that runs
+  `eslint --max-warnings 0`. `eslint --fix` removes the directives; alternatively set
+  `linterOptions: { reportUnusedDisableDirectives: 'off' }` in a config object of your own.
+
+  ### What stops being caught
+
+  Most of the churn below is substitution: a rule is renamed, split or superseded, and the same code
+  is still reported by its replacement. These are the reductions where nothing in this package takes
+  over.
+
+  | No longer reported                               | Configs | Picked up by |
+  | ------------------------------------------------ | ------- | ------------ |
+  | `while (true)`                                   | all     | nothing      |
+  | a function declaration inside a block            | all     | nothing      |
+  | assigning to a class binding (`no-class-assign`) | `.ts`   | `tsc`        |
+  | `with (obj) {}` (`no-with`)                      | `.ts`   | `tsc`        |
+  | stray semicolons, mixed spaces and tabs          | `.ts`   | prettier     |
+
+  The first two are the ESLint 9 default changes described above; they apply to every config. The
+  other three are only switched off for TypeScript files, by `@typescript-eslint` v8 and by ESLint 9
+  dropping two deprecated formatting rules from `eslint:recommended`.
+
+  Separately, and in the other direction: `vue/jsx-uses-vars` no longer applies outside `.vue` files.
+  It suppresses `no-unused-vars` for identifiers used only in JSX, so if you enable JSX in your own
+  config you may see new false `no-unused-vars` reports. Re-enable the rule yourself if so. These
+  configs never enabled JSX, so nothing changes unless you did.
+
+  ### Rules whose severity changes
+
+  25 rules change in a severity-visible way: they turn on, turn off, or are replaced by a differently
+  named rule. Everything else resolves to the same severity it did before. The causes are the
+  dependency majors listed above — none of these are a change of intent by this package.
+
+  **`vue` and `default` — 5 rules.** These hit the widest audience:
+
+  - `vue/component-tags-order` (`error`) is **gone**, replaced by `vue/block-order` (`error`) with
+    the same `{ order }` option. Rename any override you have; see the note above on why a stale
+    override is a hard error rather than a no-op.
+  - `vue/no-required-prop-with-default` is **newly on at `warn`**. eslint-plugin-vue v10 added it to
+    the recommended presets. It fires on ordinary, unchanged Vue 2 code, and because it is a warning
+    rather than an error it will **fail any build running `eslint --max-warnings 0`** while passing a
+    plain `eslint` run. If that describes your CI, expect this one to break it. Either fix the props
+    it flags or set `'vue/no-required-prop-with-default': 'off'` in your own config.
+  - `vue/comment-directive` and `vue/jsx-uses-vars` **no longer apply outside `.vue` files**.
+    eslint-plugin-vue v10 scopes both to `**/*.vue`, where v9 declared them for every linted file. No
+    coverage is lost: `vue/comment-directive` only ever acts on single-file-component output, and
+    `vue/jsx-uses-vars` needs `parserOptions.ecmaFeatures.jsx`, which these configs never enabled.
+
+  **`typescript`, on `.ts` and `.test.ts` files — 20 rules.** These arrive from ESLint 9's
+  `eslint:recommended` and from `@typescript-eslint` v8's `strict` preset, which only this config
+  extends. Note that they land on top of the parsing change described at the top of this changeset,
+  so a `typescript` consumer should expect new findings from both at once.
+
+  Newly reporting at `error`:
+
+  - From ESLint 9's `eslint:recommended`: `no-constant-binary-expression`, `no-empty-static-block`,
+    `no-unused-private-class-members`.
+  - From `@typescript-eslint` v8 dropping the extension-rule pair, so the core rule takes over:
+    `no-loss-of-precision`.
+  - From the `ban-types` split: `@typescript-eslint/no-empty-object-type`,
+    `@typescript-eslint/no-unsafe-function-type`, `@typescript-eslint/no-wrapper-object-types`.
+  - Replacing a dropped or renamed rule: `@typescript-eslint/no-require-imports` (for
+    `no-var-requires`), `@typescript-eslint/only-throw-error` (for `no-throw-literal`),
+    `@typescript-eslint/no-unused-expressions` (for the core rule).
+  - Moved into `recommended`, and so into `strict`, by `@typescript-eslint` v8:
+    `@typescript-eslint/prefer-namespace-keyword`.
+
+  No longer reporting — switched off, or removed from the rule set entirely:
+
+  - Dropped from `eslint:recommended` in ESLint 9, and already switched off by
+    `eslint-config-prettier` earlier in the chain, so they stay off: `no-extra-semi`,
+    `no-mixed-spaces-and-tabs`. Both are deprecated formatting rules that prettier enforces anyway.
+  - Added to `@typescript-eslint` v8's `eslint-recommended` layer, on the grounds that the TypeScript
+    compiler already reports them: `no-class-assign`, `no-with`.
+  - Superseded by the TypeScript-aware rule named above: `no-unused-expressions`.
+  - Removed from the `@typescript-eslint` v8 rule set or dropped from its `strict` preset:
+    `@typescript-eslint/ban-types`, `@typescript-eslint/no-var-requires`,
+    `@typescript-eslint/no-loss-of-precision`, `@typescript-eslint/no-throw-literal`.
+
+  The `base`, `jest`, `i18n` and `tailwind` configs have no severity changes at all.
+
+  ### `@stylistic` rules are not disabled for you
+
+  `eslint-config-prettier` v10 added 180 `@stylistic/*` entries to the formatting rules it switches
+  off. This package strips them before shipping, because it does not register the `@stylistic`
+  plugin and configuring a rule for an unregistered plugin is a hard error in flat config. So if you
+  register `@stylistic` yourself, **you do not get prettier's `@stylistic` disables from this
+  package** and its formatting rules may conflict with prettier. Apply `eslint-config-prettier` in
+  your own config, after the GitLab configs, to switch them off.
+
+  ## What has not changed
+
+  **The Vue rules still target Vue 2.** `eslint-plugin-vue` v9's `configs.recommended` resolved to the
+  Vue 2 preset, and this release deliberately maps it to v10's `flat/vue2-recommended` rather than
+  v10's `flat/recommended`, which is Vue 3. Retargeting would have added 33 rules and removed 6, which
+  is a product decision rather than something to fold into a config-format migration. Vue rule
+  coverage is unchanged in this release; a deliberate Vue 3 retarget is planned for a later one.
+
+  **No rule set was changed on purpose.** The migration is gated on frozen rule-map fixtures captured
+  from the eslintrc configs before any of this work started, and every difference between those
+  fixtures and what the flat configs resolve to is recorded and justified in the repository. The 25
+  rules listed under "Rules whose severity changes" above are the complete set of severity-visible
+  differences; the rest are ESLint 9 rendering the same configured options differently, which changes
+  no behaviour.
+
+  ## New
+
+  - Flat configs for all seven config names: `base`, `default`, `vue`, `jest`, `i18n`, `tailwind` and
+    `typescript`. Previously only `base` and `typescript` had flat equivalents, under
+    `@gitlab/eslint-plugin/eslint9`.
+
+## 21.5.0
+
+### Minor Changes
+
+- 8fa643e: Add `vue-no-popover-target-dollar-el` rule to flag and autofix unnecessary `.$el` in `:target` callbacks on `<gl-popover>` and `<gl-tooltip>`.
+
 ## 21.4.1
 
 ### Patch Changes

package/README.md

@@ -21,22 +21,27 @@ upstream later.
 - [Installation and Usage](./docs/usage.md)
 - [Creation & Development of rules](./docs/development.md)
 
-## Eslint 9 migration
+## Requirements
 
-The TS portion of this plugin has been migrated to eslint v9 and can be used as `const gitlabPlugin = require('@gitlab/eslint-plugin/eslint9');`. You still add the `@gitlab/eslint-plugin` as a dependency.
+- ESLint 9 (`^9.0.0`), configured with [flat config](https://eslint.org/docs/latest/use/configure/configuration-files) (`eslint.config.js`)
+- Node.js `^18.18.0 || ^20.9.0 || >=21.1.0`
 
-Add these overrides to your project's package.json:
+Every config this package exports is a flat config array:
 
-```json
-  "overrides": {
-    "@gitlab/eslint-plugin": {
-      "@typescript-eslint/eslint-plugin": "^8.38.0",
-      "@typescript-eslint/parser": "^8.38.0"
-    }
-  }
+```js
+const gitlab = require('@gitlab/eslint-plugin');
+
+module.exports = [...gitlab.configs.default];
 ```
 
-(replace the versions with what your main project uses)
+The eslintrc configs (`extends: ['plugin:@gitlab/default']`) were removed in this major release.
+See [Installation and Usage](./docs/usage.md#migrating-from-the-eslintrc-configs) for the
+migration.
+
+Using the `typescript` config additionally requires `@typescript-eslint/parser`,
+`@typescript-eslint/eslint-plugin` and `typescript` in your own project. They are optional peer
+dependencies, so your project controls their versions — the `overrides` workaround this README used
+to document is no longer needed.
 
 ## Contribution guidelines
 

package/docs/development.md

@@ -8,7 +8,8 @@ Always `yarn install` before doing things.
    a [lefthook](https://github.com/Arkweid/lefthook) `pre-commit` hook.
 2. This project adheres to semantic commits,
    use a tool like [git-cz](https://www.npmjs.com/package/git-cz) to write commit messages
-3. There is a script `yarn update` which updates `docs/rules.md` and `lib/index.js`,
+3. There is a script `yarn update` which regenerates `lib/plugin.js` (the rule map),
+   `lib/index.js` (the config getters) and `docs/rules.md` (the rule index),
    please run it after creating or updating rules.
 
 ## Creating rules

package/docs/rules/vue-no-popover-target-dollar-el.md

@@ -0,0 +1,69 @@
+# @gitlab/vue-no-popover-target-dollar-el
+
+Disallows function-form `:target` bindings on `<gl-popover>` and `<gl-tooltip>` where
+the callback body ends in `.$el`.
+
+`GlPopover` and `GlTooltip` accept a `:target` prop that is either a reference or a
+zero-argument function returning one. The reference can be a plain DOM element
+[or a Vue component instance](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/merge_requests/6006).
+The components use `.$el` automatically when it exists, so accessing it
+manually is unnecessary. This helps to avoid reference errors during teardown,
+or other cases where the ref does not exist at the time the `target` function
+is called.
+
+## Rule Details
+
+### Examples of **incorrect** code for this rule
+
+```html
+<!-- Arrow function returning .$el -->
+<gl-popover :target="() => $refs.myButton.$el" />
+
+<!-- Arrow function with explicit this -->
+<gl-tooltip :target="() => this.$refs.myButton.$el" />
+
+<!-- Function expression -->
+<gl-popover :target="function() { return $refs.myButton.$el; }" />
+
+<!-- PascalCase component names -->
+<GlPopover :target="() => $refs.myButton.$el" />
+<GlTooltip :target="() => $refs.myButton.$el" />
+
+<!-- v-bind: long-form syntax -->
+<gl-popover v-bind:target="() => $refs.myButton.$el" />
+
+<!-- Detection is not limited to `$refs`: any callback returning a
+     component instance's `.$el` is flagged -->
+<gl-popover :target="() => this.myButton.$el" />
+```
+
+### Examples of **correct** code for this rule
+
+```html
+<!-- Plain ref (no function) — always fine -->
+<gl-popover :target="$refs.myButton" />
+
+<!-- Arrow function without .$el — already correct -->
+<gl-popover :target="() => $refs.myButton" />
+
+<!-- DOM query — no .$el needed -->
+<gl-popover :target="() => document.querySelector('#my-button')" />
+
+<!-- .:target on an unrelated component — not flagged -->
+<my-component :target="() => $refs.foo.$el" />
+```
+
+## Options
+
+Nothing
+
+## Related rules
+
+- [`vue-no-data-toggle`](./vue-no-data-toggle.md)
+
+## When Not To Use It
+
+If your project is still using a version of `@gitlab/ui` that has **not** yet received the
+companion fix (design.gitlab.com!6006), enabling this rule as `error` may cause runtime
+issues. In that case, land the rule as `warn` or keep it off until the updated `@gitlab/ui`
+version is deployed.

package/docs/rules.md

@@ -16,6 +16,7 @@ Available rules:
 - [vue-no-data-toggle](./rules/vue-no-data-toggle.md): Restrict the use of `data-toggle` bootstrap behaviors within Vue templates
 - [vue-no-hardcoded-urls](./rules/vue-no-hardcoded-urls.md): Disallow hardcoded URLs in Vue templates
 - [vue-no-new-non-primitive-in-template](./rules/vue-no-new-non-primitive-in-template.md): Prevents non-primitive values from being declared in templates
+- [vue-no-popover-target-dollar-el](./rules/vue-no-popover-target-dollar-el.md): Disallow function-form `:target` bindings ending in `.$el` on `<gl-popover>` and `<gl-tooltip>`
 - [vue-no-undef-apollo-properties](./rules/vue-no-undef-apollo-properties.md): Require Apollo query properties to be initialized in component data.
 - [vue-prefer-dollar-scopedslots](./rules/vue-prefer-dollar-scopedslots.md): Prefer $scopedSlots over $slots for Vue 2.x.
 - [vue-require-i18n-attribute-strings](./rules/vue-require-i18n-attribute-strings.md): Detect non externalized strings in vue `<template>` attributes

package/docs/usage.md

@@ -1,9 +1,10 @@
 ## Installation
 
-You'll first need to install [ESLint](http://eslint.org):
+You'll first need to install [ESLint](http://eslint.org) 9. The peer dependency is `^9.0.0`:
+ESLint 8 and below are not supported, and ESLint 10 is not supported either.
 
 ```bash
-yarn add --dev eslint
+yarn add --dev eslint@^9.0.0
 ```
 
 Next, install `@gitlab/eslint-plugin`:
@@ -16,80 +17,190 @@ yarn add --dev @gitlab/eslint-plugin
 
 ## Usage (configs)
 
-### `plugin:@gitlab/default`
+All configs are [flat configs](https://eslint.org/docs/latest/use/configure/configuration-files),
+so they belong in an `eslint.config.js` (or `.mjs`/`.cjs`) file. Each one is an **array** of flat
+config objects, which you spread into your own array:
 
-Add `plugin:@gitlab/default` to the extends section of your `.eslintrc` configuration file.
-This config is for our common javascript and Vue rules.
+```js
+const gitlab = require('@gitlab/eslint-plugin');
 
-```yaml
-extends:
-  - 'plugin:@gitlab/default'
+module.exports = [...gitlab.configs.default];
 ```
 
-`plugin:@gitlab/default` uses the `espree` parser, shipped with `eslint` under the hood.
+ESM works the same way:
 
-The configured JS version is `latest`, so eslint should be able to parse even the newest JS syntax.
-You can adjust this behavior as [described here][ecma-version]. For example:
+```js
+import gitlab from '@gitlab/eslint-plugin';
 
-```yaml
-parserOptions:
-  ecmaVersion: 2020
+export default [...gitlab.configs.default];
 ```
 
-That being said, when it comes to globals, we still assume a `ES2015` environment, which brought us `Set`, `Map`.
-If you need newer globals, you can define newer env as [described here][globals]. For example:
+### Available configs
 
-```yaml
-env:
-  es2022: true
+| Config       | Contents                                                                                                               |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `default`    | The GitLab JavaScript and Vue rules together. What most projects want.                                                 |
+| `base`       | GitLab JavaScript style guide rules only, with no Vue rules.                                                           |
+| `vue`        | GitLab Vue style guide rules on top of `eslint-plugin-vue`'s recommended set. Vue rules only — combine it with `base`. |
+| `typescript` | `base` plus the TypeScript layer. Requires extra dependencies, see [TypeScript](#typescript).                          |
+| `jest`       | Jest rules, on top of `eslint-plugin-jest`'s recommended set. Requires `jest` in your project.                         |
+| `i18n`       | i18n linting for the GitLab project.                                                                                   |
+| `tailwind`   | Tailwind utility-class rules.                                                                                          |
+
+`default` is not simply `base` followed by `vue`: the two configs place
+[`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) differently relative
+to the Vue preset, which is deliberate and matches what these configs have always resolved to. Use
+`default` if you want both; use `base` and `vue` separately only if you need to interleave something
+between them.
+
+### Composing configs
+
+Because every config is an array, you can spread several of them:
+
+```js
+const gitlab = require('@gitlab/eslint-plugin');
+
+module.exports = [...gitlab.configs.default, ...gitlab.configs.i18n];
+```
+
+The configs are not restricted to particular files, so they apply to everything ESLint lints. To
+scope one to a subset of your project, add a `files` pattern to each of its entries:
+
+```js
+const gitlab = require('@gitlab/eslint-plugin');
+
+module.exports = [
+  ...gitlab.configs.default,
+  ...gitlab.configs.jest.map((config) => ({ ...config, files: ['**/*.spec.js'] })),
+];
+```
+
+**Do not do this to `vue`, `default` or `typescript`.** Those three already set `files` on some of
+their entries, and `{ ...config, files: [...] }` overwrites that key rather than narrowing it. On
+`vue` and `default` you would drop the scope from the two `**/*.vue` entries, so Vue
+single-file-component rules would start applying to plain `.js` files. On `typescript` you would
+drop the scope from its `**/*.ts` and `**/*.test.ts` entries, so the TypeScript parser and the
+type-aware rules would be applied to every file the pattern matches — including `.spec.js`, which
+they cannot parse. Scope those configs by narrowing the patterns they
+already declare, or by adding your own config object after them, not by replacing `files` wholesale.
+`jest`, `i18n`, `tailwind` and `base` declare no `files` key and are safe to map this way.
+
+### Parsers and language options
+
+`base` and `default` use `espree`, shipped with `eslint`, at `ecmaVersion: 'latest'`, so even the
+newest JavaScript syntax parses. `vue` (and therefore `default`) uses
+[`vue-eslint-parser`](https://github.com/vuejs/vue-eslint-parser) with `espree` for `<script>`
+blocks.
+
+To change a language option, add a config object of your own after the GitLab configs — later
+entries win:
+
+```js
+const gitlab = require('@gitlab/eslint-plugin');
+
+module.exports = [
+  ...gitlab.configs.default,
+  {
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: {
+        gon: 'readonly',
+      },
+    },
+  },
+];
 ```
 
-If you want to completely swap out the parser (e.g. using a typescript or babel parser), please follow
-the [`eslint` docs][eslint-parser-config] if you only lint JS files,
-and the [`vue-eslint-parser` docs][vue-eslint-parser-config] if you lint VUE files as well.
+See the ESLint docs on [language options][language-options] and
+[configuring a parser][eslint-parser-config] for the full set of keys.
 
-[ecma-version]: https://eslint.org/docs/latest/use/configure/language-options#specifying-parser-options
-[globals]: https://eslint.org/docs/latest/use/configure/language-options#specifying-environments
+[language-options]: https://eslint.org/docs/latest/use/configure/language-options
 [eslint-parser-config]: https://eslint.org/docs/latest/use/configure/parser
-[vue-eslint-parser-config]: https://eslint.vuejs.org/user-guide/#how-to-use-a-custom-parser
 
-### `plugin:@gitlab/i18n`
+### TypeScript
 
-Add `plugin:@gitlab/i18n` to the extends section of your `.eslintrc` configuration file.
-This config is for i18n linting on the GitLab project.
+The `typescript` config needs `@typescript-eslint/parser`, `@typescript-eslint/eslint-plugin` and
+`typescript` in your own project. They are optional peer dependencies of this package, so your
+project controls their versions:
 
-```yaml
-extends:
-  - 'plugin:@gitlab/i18n'
+```bash
+yarn add --dev typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin
 ```
 
-### `plugin:@gitlab/jest`
+```js
+const gitlab = require('@gitlab/eslint-plugin');
 
-Add `plugin:@gitlab/jest` to the extends section of your `.eslintrc` configuration file.
-This config is for Jest rules.
+module.exports = [...gitlab.configs.typescript];
+```
 
-```yaml
-extends:
-  - 'plugin:@gitlab/jest'
+The `**/*.ts` layer is type-aware: it sets `parserOptions.project` to `./tsconfig.json`, so a
+`tsconfig.json` must exist at the directory ESLint runs from and must include the files you lint.
+If your `tsconfig.json` lives elsewhere, override it after spreading the config:
+
+```js
+const gitlab = require('@gitlab/eslint-plugin');
+
+module.exports = [
+  ...gitlab.configs.typescript,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parserOptions: { project: ['./config/tsconfig.eslint.json'] },
+    },
+  },
+];
 ```
 
+Requiring `@gitlab/eslint-plugin` does **not** load the TypeScript packages unless you actually read
+`configs.typescript`; each config is exposed through a getter. One consequence: spreading the whole
+`configs` object (`{ ...gitlab.configs }`), deep-cloning it or passing it to `JSON.stringify` reads
+every config at once and throws if the TypeScript packages are not installed. Read the configs you
+need by name instead.
+
 ## Usage (rules)
 
-Add `@gitlab` to the plugins section of your `.eslintrc` configuration file:
+To use individual rules without one of the configs, register the plugin yourself and enable the
+rules you want:
+
+```js
+const gitlab = require('@gitlab/eslint-plugin');
 
-```yaml
-plugins:
-  - @gitlab
+module.exports = [
+  {
+    plugins: { '@gitlab': gitlab },
+    rules: {
+      '@gitlab/require-i18n-strings': 'error',
+    },
+  },
+];
 ```
 
-Then configure the rules you want to use under the rules section, for example:
+See [Available rules](./rules.md) for the full list.
 
-YAML:
+## Migrating from the eslintrc configs
 
-```yaml
-rules:
-  '@gitlab/vue-require-i18n-attribute-strings': error
-```
+Up to and including v21, this package shipped eslintrc configs used through `extends`. Those are
+gone. The replacement is a spread of the same-named config:
+
+| Before (`.eslintrc.yml`)                 | After (`eslint.config.js`)     |
+| ---------------------------------------- | ------------------------------ |
+| `extends: ['plugin:@gitlab/default']`    | `...gitlab.configs.default`    |
+| `extends: ['plugin:@gitlab/base']`       | `...gitlab.configs.base`       |
+| `extends: ['plugin:@gitlab/vue']`        | `...gitlab.configs.vue`        |
+| `extends: ['plugin:@gitlab/typescript']` | `...gitlab.configs.typescript` |
+| `extends: ['plugin:@gitlab/jest']`       | `...gitlab.configs.jest`       |
+| `extends: ['plugin:@gitlab/i18n']`       | `...gitlab.configs.i18n`       |
+| `extends: ['plugin:@gitlab/tailwind']`   | `...gitlab.configs.tailwind`   |
+
+The eight fragments that `base` is assembled from — `plugin:@gitlab/best-practices`,
+`plugin:@gitlab/errors`, `plugin:@gitlab/es6`, `plugin:@gitlab/imports`, `plugin:@gitlab/node`,
+`plugin:@gitlab/strict`, `plugin:@gitlab/style` and `plugin:@gitlab/variables` — were also exported
+as configs. They are no longer part of the public surface; extend `base` instead.
+
+ESLint's own [configuration migration guide][eslint-migration] covers the rest of the move, and
+`npx @eslint/migrate-config .eslintrc` can convert the parts of your config that are not GitLab's.
+
+[eslint-migration]: https://eslint.org/docs/latest/use/configure/migration-guide
 
 ## VueJS (.vue files)
 

package/eslint9/index.js

@@ -1,9 +1,8 @@
 /**
- * This file is GENERATED, please run `yarn update` after adding or renaming a rule
+ * @deprecated Use the package root instead:
+ *   const gitlab = require('@gitlab/eslint-plugin');
+ *
+ * Kept so existing `@gitlab/eslint-plugin/eslint9` imports keep resolving.
+ * Scheduled for removal in the ESLint 10 major.
  */
-module.exports = {
-  configs: {
-    base: require('./configs/base.js'),
-    typescript: require('./configs/typescript.js'),
-  },
-};
+module.exports = require('../lib/index.js');

package/lib/configs/base/best-practices.js

@@ -1,8 +1,4 @@
 module.exports = {
-  parserOptions: {
-    ecmaVersion: 2018,
-    sourceType: 'module',
-  },
   rules: {
     // enforces getter/setter pairs in objects
     // https://eslint.org/docs/rules/accessor-pairs

package/lib/configs/base/es6.js

@@ -1,16 +1,4 @@
 module.exports = {
-  env: {
-    es6: true,
-  },
-  parserOptions: {
-    ecmaVersion: 6,
-    sourceType: 'module',
-    ecmaFeatures: {
-      generators: false,
-      objectLiteralDuplicateProperties: false,
-    },
-  },
-
   rules: {
     // enforces no braces where they can be omitted
     // https://eslint.org/docs/rules/arrow-body-style