pigui/pireon-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Josep Piguillem
2026-07-27 18:01:07 +02:00
commit 0758b00d54
192 changed files with 45091 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

291
tools/ai-migrations/@nx/eslint/23.1.0/convert-to-flat-config.md Normal file
View File

@@ -0,0 +1,291 @@
# ESLint v9 Flat Config Migration Instructions for LLM
## Overview
These instructions guide you through finishing the migration of an Nx workspace to ESLint v9.
ESLint v9 makes flat config (`eslint.config.{mjs,cjs,js}`) the default config format. The legacy eslintrc format (`.eslintrc.*`) still works at runtime, but only when `ESLINT_USE_FLAT_CONFIG=false` is set, so Nx converts workspaces to flat config instead of relying on that escape hatch.
The migration runs in two halves:
1. A deterministic pre-pass (the `@nx/eslint:convert-to-flat-config` generator) that already converted the JSON and YAML eslintrc configs.
2. This prompt: finish the parts that need judgment and leave the workspace lint-passing.
Work systematically through each section below.
<pre_pass_summary note="a deterministic pre-pass already applied these edits; verify the new shape is in place rather than redoing them">
The pre-pass handled, mechanically:
- Converted the root and per-project JSON/YAML eslintrc files to `eslint.config.mjs`:
- `eslint:recommended` to `js.configs.recommended`
- `@nx/*` presets to their flat-config equivalents
- `env` to `languageOptions.globals`
- `parser` / `parserOptions` to `languageOptions`
- `plugins` to the flat `plugins` object
- `ignorePatterns` and `.eslintignore` to `ignores`
- stale `.eslintrc`/`.eslintignore` references in `nx.json` and `project.json` inputs
- Added `@eslint/js` and `@eslint/eslintrc` to `package.json` when the converted config needs them.
The pre-pass does NOT:
- Convert JavaScript-based eslintrc files (`.eslintrc.js`, `.eslintrc.cjs`). It cannot evaluate them safely.
- Change the output formatter a lint target uses.
- Decide whether a generated `FlatCompat` shim should become flat-native config.
- Make the workspace pass lint after ESLint v9 changed which rules its preset defaults enable.
Everything the pre-pass could not finish is forwarded to you in `<advisory_context>`.
How to read the wrapper sections above this file:
- `<files_changed>` lists files the pre-pass wrote. Verify the new shape is in place; do not re-apply the same edit. It is absent when the pre-pass made no changes (for example a workspace that was already on flat config).
- `<advisory_context>` lists detections the pre-pass forwarded because it could not safely complete them. Every entry is pending work. Address each one in the relevant section below.
</pre_pass_summary>
<handoff_guidance>
In your handoff `summary` (1 to 3 sentences per the system prompt), name the sections you applied and explicitly call out any you skipped because they did not apply (for example "no JavaScript-based configs and no removed formatters in this workspace").
</handoff_guidance>
## Pre-Migration Checklist
1. **Confirm the ESLint version is v9**:
```bash
npx eslint --version
```
2. **Locate all ESLint config files**:
- Flat configs: `eslint.config.{mjs,cjs,js}` at the root and in each project.
- Any remaining eslintrc files: `.eslintrc`, `.eslintrc.json`, `.eslintrc.yaml`, `.eslintrc.yml`, `.eslintrc.js`, `.eslintrc.cjs`.
- Ignore files: `.eslintignore`.
3. **Identify all lint targets**:
```bash
nx show projects --with-target lint
```
Check `project.json` files for the `@nx/eslint:lint` executor or `eslint` run-commands. Workspaces using the inferred plugin (`@nx/eslint/plugin`) get lint targets from the presence of `eslint.config.*`; inspect them with `nx show project <name> --json`.
4. **Identify local ESLint rules or plugins** authored inside the workspace. These use the rule API that changed in v9 (see section 6).
---
## Nx-Specific Notes (read first)
- **Flat config is the default in v9**. eslintrc only resolves when `ESLINT_USE_FLAT_CONFIG=false` is set. Nx converts the workspace to flat config so that no environment variable is required.
- **Shared base config pattern**: many Nx workspaces have a root `eslint.config.mjs` that each project imports, for example `import baseConfig from '../../eslint.config.mjs'`. Convert and verify the base config first, then the per-project configs.
- **Inferred plugin targets**: `@nx/eslint/plugin` infers the lint target from the presence of `eslint.config.*`. Renaming or moving the config invalidates inference. After config edits, run `nx reset && nx show project <name>` on a sample project to confirm the target is still present.
- **FlatCompat shim**: when the pre-pass could not translate a third-party `extends` or a complex override natively, it emitted a `FlatCompat` shim (from the `@eslint/eslintrc` package). That config works as-is, but section 3 covers replacing it with flat-native config where low-risk.
---
## 1. Already on flat config? Verify only
If the workspace already uses `eslint.config.*` at the root and in every project, with no remaining `.eslintrc.*` files, do NOT restructure it. The only required work is the passing-state check in section 4: a workspace on ESLint v9 can newly fail because v9 and typescript-eslint v8 changed which rules their recommended sets enable, even when the config was already flat.
## 2. Convert JavaScript-based ESLint configs the pre-pass skipped
**Search pattern**: `.eslintrc.js` and `.eslintrc.cjs` files (forwarded in `<advisory_context>`).
**What changed**: the pre-pass only converts JSON and YAML eslintrc files. JavaScript-based configs run arbitrary code, so they need manual conversion.
```js
// BEFORE (.eslintrc.js)
module.exports = {
extends: ['../../.eslintrc.json'],
overrides: [
{
files: ['*.ts'],
rules: { '@typescript-eslint/no-explicit-any': 'error' },
},
],
};
```
```js
// AFTER (eslint.config.mjs)
import baseConfig from '../../eslint.config.mjs';
export default [
...baseConfig,
{
files: ['**/*.ts'],
rules: { '@typescript-eslint/no-explicit-any': 'error' },
},
];
```
**Action items**:
- [ ] Convert each JavaScript-based config to `eslint.config.mjs`, mirroring the structure the pre-pass produced for the JSON/YAML configs.
- [ ] Preserve the existing rules, plugins, parser options, and overrides.
- [ ] Delete the original `.eslintrc.js` / `.eslintrc.cjs` once the flat config replaces it.
- [ ] Update any `project.json` / `nx.json` inputs that referenced the old file name.
## 3. Convert FlatCompat shims to flat-native config where low-risk
**Search pattern**: `FlatCompat`, `@eslint/eslintrc`, `compat.extends(`, `compat.config(` in the generated `eslint.config.*` files (listed in `<files_changed>`).
**What changed**: `FlatCompat` is a runtime shim that adapts eslintrc-style `extends` into flat config. Many plugins now ship native flat presets, which are clearer and avoid the shim.
**Decision rule**: convert a `FlatCompat` usage to flat-native config when it is low-risk, otherwise keep the shim.
- Low-risk (prefer flat-native): typescript-eslint configs, and plugins that document a flat preset (for example `eslint-plugin-react`, `eslint-plugin-import`).
- Keep the shim: third-party shared configs that do not document a flat-config entry point.
```js
// BEFORE (FlatCompat shim, eslint.config.mjs)
import js from '@eslint/js';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import { FlatCompat } from '@eslint/eslintrc';
const compat = new FlatCompat({
baseDirectory: dirname(fileURLToPath(import.meta.url)),
recommendedConfig: js.configs.recommended,
});
export default [...compat.extends('plugin:@typescript-eslint/recommended')];
```
```js
// AFTER (flat-native, eslint.config.mjs)
import tseslint from 'typescript-eslint';
export default [...tseslint.configs.recommended];
```
**Action items**:
- [ ] For each `FlatCompat` usage, decide flat-native vs keep-the-shim using the rule above.
- [ ] When converting, drop the now-unused `@eslint/eslintrc` import if no shim remains in that file.
- [ ] Re-run lint after each change to confirm the rule set did not silently shift.
## 4. Restore the passing baseline (required)
This is the core requirement of the migration: the workspace must lint cleanly when you are done.
ESLint v9 and typescript-eslint v8 changed which rules their recommended sets enable. A rule the user never configured may now report errors. Disable those rules; do not edit source files to satisfy them.
The set of rules the user explicitly configured before the migration is in `<advisory_context>` (the entry that starts with "Passing-state requirement").
**Procedure**:
1. Run lint across the workspace:
```bash
nx run-many -t lint
```
2. Tell a rule violation apart from a plugin crash. If a project fails with a thrown error instead of rule findings - a `TypeError` such as `context.getAncestors is not a function`, a `Could not find "<rule>" in plugin "<name>"` / `couldn't find the config "<name>" to extend from`, or a plugin that fails to load - the plugin predates ESLint v9; this is not a changed preset default. Do NOT disable the rule (that silently drops its coverage); update the plugin instead (section 6), then re-run lint and continue.
3. For each rule that now reports errors (findings, not a thrown error):
- If the rule ID is NOT in the user's explicit list, it came from a changed preset default. Disable it in the relevant flat config with a short comment explaining why.
- If the rule ID IS in the user's explicit list, the user chose it. Leave it as-is and report it in your handoff summary.
```js
// Disable a rule that a changed preset default newly enabled (eslint.config.mjs).
export default [
...baseConfig,
{
files: ['**/*.ts'],
rules: {
// Newly enabled by the ESLint v9 recommended set; was not enforced before the upgrade.
'no-unused-expressions': 'off',
},
},
];
```
**Action items**:
- [ ] Run lint and collect every newly reported rule.
- [ ] Treat a plugin crash (a thrown error, not rule findings) as a version incompatibility: update the plugin (section 6), never disable its rules to silence it.
- [ ] Disable preset-originated rules that the user did not configure.
- [ ] Never disable or weaken a rule the user explicitly configured.
- [ ] Never edit source files to satisfy a newly enabled rule.
<fail_if note="if you cannot reach a passing state without editing source or disabling a user-configured rule, stop and report">
You cannot make lint pass without either editing source files or disabling a rule the user explicitly configured. Write status: failed and explain which rule and project in your summary. Do not guess.
</fail_if>
## 5. Fix removed output formatters
**Search pattern**: the `format` option on lint targets (forwarded in `<advisory_context>`).
**What changed**: ESLint v9 removed several built-in output formatters. The built-ins that remain are `stylish`, `html`, `json`, and `json-with-metadata`. Removed: `compact`, `codeframe`, `unix`, `visualstudio`, `table`, `checkstyle`, `jslint-xml`, `junit`, `tap`.
**Fix**: switch the target to a built-in that remains, or install the matching community package and reference it by its package name.
```bash
# Example: keep junit output by installing the community formatter package.
npm install --save-dev eslint-formatter-junit
```
```jsonc
// project.json (reference the community formatter by package name)
"lint": {
"executor": "@nx/eslint:lint",
"options": { "format": "eslint-formatter-junit" }
}
```
**Action items**:
- [ ] For each flagged target, switch to a remaining built-in formatter or a community package.
- [ ] When using a community package, add it to `devDependencies`.
## 6. Other ESLint v9 runtime breaking changes
**Search pattern**: lint executor options, run-commands invoking `eslint`, and local rule/plugin source.
- **Removed CLI flags and executor options**: `--rulesdir`, `--ext`, and `--resolve-plugins-relative-to` were removed. The matching `@nx/eslint:lint` options (`rulesdir`, `resolvePluginsRelativeTo`, `ignorePath`) are not supported for flat config. Move file targeting into the config via the `files` and `ignores` keys.
- **No eslintrc auto-merge**: flat config does not merge `.eslintrc.*` files found up the tree. Every setting must live in `eslint.config.*`.
- **Third-party plugins that predate ESLint v9**: an installed ESLint plugin that was not updated for v9 breaks at lint time - its rules call the removed `context` APIs below, or it only ships an eslintrc config that no longer loads. This surfaces as a thrown error (see section 4), not a new rule violation. List the installed plugins from `package.json` (`dependencies`/`devDependencies` matching `eslint-plugin-*` or `@<scope>/eslint-plugin-*`), and for each confirm its version supports ESLint v9 (its changelog, or that `peerDependencies.eslint` allows `>=9`). Update any that do not, and prefer the plugin's flat entry point where it ships one (for example `eslint-plugin-cypress/flat`). Update the plugin rather than disabling its rules.
- **Local rule API moved to `SourceCode`** (only relevant if the workspace authors its own rules):
- `context.getScope()` to `sourceCode.getScope(node)`
- `context.getAncestors()` to `sourceCode.getAncestors(node)`
- `context.getDeclaredVariables()` to `sourceCode.getDeclaredVariables(node)`
- `context.markVariableAsUsed(name)` to `sourceCode.markVariableAsUsed(name, node)`
- `context.getSource()` to `sourceCode.getText()`
- `context.parserServices` to `sourceCode.parserServices`
- **Stricter rule schema**: a custom rule that accepts options must declare `meta.schema` in v9.
**Action items**:
- [ ] Remove unsupported CLI flags and executor options; move targeting into `files` / `ignores`.
- [ ] Update any installed third-party ESLint plugin that does not yet support ESLint v9, preferring its flat entry point; do not disable its rules to work around a load error.
- [ ] Update local rules to the `SourceCode` API and add `meta.schema` where required.
---
## Post-Migration Verification
1. Clear the inference cache so renamed configs are re-detected:
```bash
nx reset
```
2. Confirm lint passes across the workspace:
```bash
nx run-many -t lint
```
3. Spot-check that a converted project resolves its config:
```bash
npx eslint --print-config <a-file-in-the-project>
```
4. Confirm no `.eslintrc.*` files remain unless one was intentionally kept.
## References
- ESLint configuration files (flat config): https://eslint.org/docs/latest/use/configure/configuration-files
- Migrate to ESLint v9.0.0: https://eslint.org/docs/latest/use/migrate-to-9.0.0
- typescript-eslint configs: https://typescript-eslint.io/users/configs
- Nx ESLint plugin: https://nx.dev/nx-api/eslint