@nx/eslint 23.0.0 → 23.1.0-beta.0

package/dist/src/migrations/update-23-1-0/convert-to-flat-config.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = update;
+const devkit_1 = require("@nx/devkit");
+const config_file_1 = require("../../utils/config-file");
+const generator_1 = require("../../generators/convert-to-flat-config/generator");
+// Output formatters ESLint removed in v9. Built-in names only; community
+// formatter packages (referenced by their package name) keep working.
+const REMOVED_FORMATTERS = new Set([
+    'compact',
+    'codeframe',
+    'unix',
+    'visualstudio',
+    'table',
+    'checkstyle',
+    'jslint-xml',
+    'junit',
+    'tap',
+]);
+// Executor options the flat-config lint executor rejects outright (it throws when
+// any is present). The generator folds project-level `ignorePath` into the flat
+// config `ignores`, so that one is reported only when inherited from targetDefaults.
+const FLAT_CONFIG_UNSUPPORTED_OPTIONS = [
+    'ignorePath',
+    'resolvePluginsRelativeTo',
+    'reportUnusedDisableDirectives',
+];
+const ROOT_ESLINTRC_CANDIDATES = [
+    '.eslintrc.base.json',
+    '.eslintrc',
+    '.eslintrc.json',
+    '.eslintrc.yaml',
+    '.eslintrc.yml',
+];
+const ESLINT_LINT_EXECUTOR = '@nx/eslint:lint';
+/**
+ * Hybrid migration paired with `convert-to-flat-config.md`. The deterministic
+ * half reuses the `@nx/eslint:convert-to-flat-config` generator to convert
+ * JSON/YAML eslintrc configs to flat config (the version bump is owned by
+ * `packageJsonUpdates`, so it runs with `keepExistingVersions`). It then returns
+ * `agentContext` describing the work the generator could not do deterministically
+ * (JavaScript-based configs, removed output formatters, the passing-state
+ * baseline) so the paired prompt's agent can finish the job and keep the
+ * workspace lint-passing.
+ */
+async function update(tree) {
+    // Gather pre-conversion context: the generator deletes the eslintrc files it
+    // converts, so anything derived from them must be captured first.
+    const userExplicitRules = collectUserRuleIds(tree);
+    const skippedJsConfigs = findJsProjectConfigs(tree);
+    const removedFormatterTargets = findRemovedFormatterTargets(tree);
+    const unsupportedOptionTargets = findUnsupportedFlatConfigOptionTargets(tree);
+    const rootState = detectRootConfigState(tree);
+    if (rootState === 'none') {
+        // No ESLint configuration to migrate.
+        return;
+    }
+    if (rootState === 'convertible') {
+        await (0, generator_1.convertToFlatConfigGenerator)(tree, {
+            keepExistingVersions: true,
+            skipFormat: false,
+        });
+    }
+    const agentContext = [
+        passingBaselineInstruction(userExplicitRules),
+    ];
+    const nextSteps = [];
+    if (rootState === 'js') {
+        agentContext.push('The root ESLint config is JavaScript-based (.eslintrc.js or .eslintrc.cjs) and was not converted automatically. ' +
+            'Convert the whole workspace to flat config by hand: produce an eslint.config.mjs at the root and one per project, ' +
+            'preserving the existing rules, plugins, parser options and overrides.');
+        nextSteps.push('The root ESLint config is JavaScript-based and must be converted to flat config manually (root and every project).');
+    }
+    if (skippedJsConfigs.length > 0) {
+        agentContext.push(`These project ESLint configs are JavaScript-based and were not converted automatically: ${skippedJsConfigs.join(', ')}. Convert each one to a flat config (eslint.config.mjs) manually, mirroring the conversion applied to the JSON/YAML configs.`);
+        nextSteps.push(`Convert these JavaScript-based ESLint configs to flat config manually: ${skippedJsConfigs.join(', ')}.`);
+    }
+    if (removedFormatterTargets.length > 0) {
+        agentContext.push(`These lint targets use an ESLint output formatter that was removed in v9: ${removedFormatterTargets.join('; ')}. Switch each to a built-in formatter (stylish, html, json, json-with-metadata) or install the matching community package (for example eslint-formatter-junit) and reference it by its package name.`);
+        nextSteps.push(`Update lint targets that use a removed ESLint formatter: ${removedFormatterTargets.join('; ')}.`);
+    }
+    if (unsupportedOptionTargets.length > 0) {
+        agentContext.push(`These lint targets set an ESLint option that flat config no longer supports, so the flat-config executor will throw: ${unsupportedOptionTargets.join('; ')}. Remove each option from its target or nx.json targetDefaults and migrate the behavior into the flat config where it applies: fold ignorePath patterns into the ignores block, set reportUnusedDisableDirectives via linterOptions. resolvePluginsRelativeTo has no flat-config equivalent. The workspace must still lint cleanly afterward.`);
+        nextSteps.push(`Remove ESLint executor options that flat config no longer supports: ${unsupportedOptionTargets.join('; ')}.`);
+    }
+    if (rootState === 'convertible' && generatedConfigsUseFlatCompat(tree)) {
+        agentContext.push('One or more generated flat configs use the FlatCompat shim from the @eslint/eslintrc package for third-party "extends" or complex overrides. ' +
+            'Convert each FlatCompat usage to flat-native config when it is low-risk (for example typescript-eslint flat configs, or plugins that ship flat presets); otherwise keep the shim. ' +
+            'The workspace must still lint cleanly afterward.');
+    }
+    return { agentContext, nextSteps };
+}
+function detectRootConfigState(tree) {
+    const hasFlatConfig = [
+        ...config_file_1.ESLINT_FLAT_CONFIG_FILENAMES,
+        ...config_file_1.BASE_ESLINT_CONFIG_FILENAMES,
+    ].some((file) => tree.exists(file));
+    if (hasFlatConfig) {
+        return 'flat';
+    }
+    if (tree.exists('.eslintrc.js') || tree.exists('.eslintrc.cjs')) {
+        return 'js';
+    }
+    if (ROOT_ESLINTRC_CANDIDATES.some((file) => tree.exists(file))) {
+        return 'convertible';
+    }
+    return 'none';
+}
+// Collects every rule ID the user explicitly configured across all eslintrc
+// layers (root, base and per-project), so the agent can tell user-chosen rules
+// apart from preset defaults when restoring the passing baseline. JavaScript
+// configs are unreadable here and are surfaced separately.
+function collectUserRuleIds(tree) {
+    const ruleIds = new Set();
+    const roots = ['', ...[...(0, devkit_1.getProjects)(tree).values()].map((p) => p.root)];
+    for (const root of roots) {
+        for (const filename of ROOT_ESLINTRC_CANDIDATES) {
+            const path = root ? `${root}/${filename}` : filename;
+            if (!tree.exists(path)) {
+                continue;
+            }
+            const config = readEslintrcConfig(tree, path);
+            if (!config) {
+                continue;
+            }
+            for (const id of Object.keys(config.rules ?? {})) {
+                ruleIds.add(id);
+            }
+            for (const override of config.overrides ?? []) {
+                for (const id of Object.keys(override?.rules ?? {})) {
+                    ruleIds.add(id);
+                }
+            }
+        }
+    }
+    return [...ruleIds].sort();
+}
+function findJsProjectConfigs(tree) {
+    const configs = [];
+    for (const [, projectConfig] of (0, devkit_1.getProjects)(tree)) {
+        for (const filename of ['.eslintrc.js', '.eslintrc.cjs']) {
+            const path = `${projectConfig.root}/${filename}`;
+            if (tree.exists(path)) {
+                configs.push(path);
+            }
+        }
+    }
+    return configs;
+}
+function findRemovedFormatterTargets(tree) {
+    const targets = [];
+    // Emits one entry per option set (default + each configuration) whose `format`
+    // names a formatter ESLint removed in v9.
+    const collectRemovedFormatters = (baseLabel, optionSets) => {
+        for (const [configuration, options] of optionSets) {
+            const format = options?.format;
+            if (typeof format === 'string' && REMOVED_FORMATTERS.has(format)) {
+                const label = configuration
+                    ? `${baseLabel}:${configuration}`
+                    : baseLabel;
+                targets.push(`${label} (format: "${format}")`);
+            }
+        }
+    };
+    for (const [project, projectConfig] of (0, devkit_1.getProjects)(tree)) {
+        for (const [targetName, target] of Object.entries(projectConfig.targets ?? {})) {
+            // Scan both the default options and every configuration, since a removed
+            // formatter is often only set on a CI-specific configuration.
+            const optionSets = [
+                [null, target.options],
+                ...Object.entries(target.configurations ?? {}),
+            ];
+            collectRemovedFormatters(`${project}:${targetName}`, optionSets);
+        }
+    }
+    // Lint options are commonly centralized in nx.json targetDefaults; a removed
+    // formatter set there is inherited by every lint target and would be missed by
+    // the per-project scan above (getProjects does not merge targetDefaults).
+    const targetDefaults = (0, devkit_1.readNxJson)(tree)?.targetDefaults ?? {};
+    for (const [name, target] of Object.entries(targetDefaults)) {
+        if (name !== 'lint' && name !== ESLINT_LINT_EXECUTOR) {
+            continue;
+        }
+        const optionSets = [[null, target.options], ...Object.entries(target.configurations ?? {})];
+        collectRemovedFormatters(`targetDefaults["${name}"]`, optionSets);
+    }
+    return targets;
+}
+// Finds lint executor options that flat config rejects and that survive the
+// conversion, so they can be surfaced for manual cleanup. The flat-config executor
+// throws on these, so an inherited one fails every affected lint target.
+function findUnsupportedFlatConfigOptionTargets(tree) {
+    const entries = [];
+    const collect = (baseLabel, optionSets, candidates) => {
+        for (const [configuration, options] of optionSets) {
+            for (const option of candidates) {
+                const value = options?.[option];
+                // reportUnusedDisableDirectives only throws when truthy; the others throw
+                // whenever they are set, matching resolveAndInstantiateESLint.
+                const present = option === 'reportUnusedDisableDirectives'
+                    ? !!value
+                    : value !== undefined;
+                if (present) {
+                    const label = configuration
+                        ? `${baseLabel}:${configuration}`
+                        : baseLabel;
+                    entries.push(`${label} (${option})`);
+                }
+            }
+        }
+    };
+    // Project lint targets keep the options the generator does not strip; it already
+    // removes `eslintConfig` and `ignorePath`, so exclude ignorePath here.
+    const projectCandidates = FLAT_CONFIG_UNSUPPORTED_OPTIONS.filter((option) => option !== 'ignorePath');
+    for (const [project, projectConfig] of (0, devkit_1.getProjects)(tree)) {
+        for (const [targetName, target] of Object.entries(projectConfig.targets ?? {})) {
+            if (target.executor !== ESLINT_LINT_EXECUTOR) {
+                continue;
+            }
+            const optionSets = [
+                [null, target.options],
+                ...Object.entries(target.configurations ?? {}),
+            ];
+            collect(`${project}:${targetName}`, optionSets, projectCandidates);
+        }
+    }
+    // targetDefaults inherit into every lint target, including `ignorePath`, which
+    // the generator only cleans up at the project level.
+    const targetDefaults = (0, devkit_1.readNxJson)(tree)?.targetDefaults ?? {};
+    for (const [name, target] of Object.entries(targetDefaults)) {
+        if (name !== 'lint' && name !== ESLINT_LINT_EXECUTOR) {
+            continue;
+        }
+        const optionSets = [[null, target.options], ...Object.entries(target.configurations ?? {})];
+        collect(`targetDefaults["${name}"]`, optionSets, FLAT_CONFIG_UNSUPPORTED_OPTIONS);
+    }
+    return entries;
+}
+// Scans the generated flat configs for the FlatCompat shim so the advisory only
+// fires when there is real compat output to assess.
+function generatedConfigsUseFlatCompat(tree) {
+    const roots = ['', ...[...(0, devkit_1.getProjects)(tree).values()].map((p) => p.root)];
+    for (const root of roots) {
+        for (const filename of [
+            ...config_file_1.ESLINT_FLAT_CONFIG_FILENAMES,
+            ...config_file_1.BASE_ESLINT_CONFIG_FILENAMES,
+        ]) {
+            const path = root ? `${root}/${filename}` : filename;
+            if (!tree.exists(path)) {
+                continue;
+            }
+            if ((tree.read(path, 'utf-8') ?? '').includes('FlatCompat')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function readEslintrcConfig(tree, path) {
+    if (path.endsWith('.yaml') || path.endsWith('.yml')) {
+        const content = tree.read(path, 'utf-8');
+        if (!content) {
+            return null;
+        }
+        const { load } = require('@zkochan/js-yaml');
+        return load(content, { json: true, filename: path });
+    }
+    try {
+        return (0, devkit_1.readJson)(tree, path);
+    }
+    catch {
+        return null;
+    }
+}
+function passingBaselineInstruction(userExplicitRules) {
+    const ruleList = userExplicitRules.length > 0
+        ? `The user explicitly configured these rules before the migration: ${userExplicitRules.join(', ')}.`
+        : 'The user did not explicitly configure any rules before the migration.';
+    return (`Passing-state requirement: after migrating, run the workspace lint and keep it passing. ${ruleList} ` +
+        'For any rule that now reports errors but is not in that list, disable it in the flat config with a short explanatory comment. ' +
+        'Those errors come from changed preset defaults (the ESLint v9 "eslint:recommended" set and the typescript-eslint v8 recommended sets), not from the user. ' +
+        'Never disable or weaken a rule the user explicitly configured, and never edit source files to satisfy a newly enabled rule.');
+}

package/dist/src/migrations/update-23-1-0/convert-to-flat-config.md

@@ -0,0 +1,286 @@
+# 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. For each rule that now reports errors:
+   - 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.
+- [ ] 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.*`.
+- **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 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

package/dist/src/plugins/plugin.js

@@ -12,7 +12,6 @@ const file_hasher_1 = require("nx/src/hasher/file-hasher");
 const cache_directory_1 = require("nx/src/utils/cache-directory");
 const globs_1 = require("nx/src/utils/globs");
 const workspace_context_1 = require("nx/src/utils/workspace-context");
-const semver_1 = require("semver");
 const config_file_1 = require("../utils/config-file");
 const resolve_eslint_class_1 = require("../utils/resolve-eslint-class");
 const DEFAULT_EXTENSIONS = [
@@ -34,7 +33,6 @@ const ESLINT_CONFIG_GLOB_V2 = (0, globs_1.combineGlobPatterns)([
 ]);
 const internalCreateNodesV2 = async (ESLint, configFilePath, options, context, projectRootsByEslintRoots, lintableFilesPerProjectRoot, tsconfigChainsByProjectRoot, projectsCache, hashByRoot, pmc) => {
     const configDir = (0, posix_1.dirname)(configFilePath);
-    const eslintVersion = ESLint.version;
     let sharedEslint;
     const getEslint = (projectRoot) => {
         if ((0, node_fs_1.existsSync)((0, posix_1.join)(context.workspaceRoot, projectRoot, '.eslintignore'))) {
@@ -75,7 +73,7 @@ const internalCreateNodesV2 = async (ESLint, configFilePath, options, context, p
             projectsCache.set(hash, {});
             return null;
         }
-        const project = getProjectUsingESLintConfig(configFilePath, projectRoot, eslintVersion, options, context, pmc, tsconfigChainsByProjectRoot.get(projectRoot) ?? []);
+        const project = getProjectUsingESLintConfig(configFilePath, projectRoot, options, context, pmc, tsconfigChainsByProjectRoot.get(projectRoot) ?? []);
         if (project) {
             const entry = { [projectRoot]: project };
             // Store project into the cache
@@ -250,7 +248,7 @@ function getRootForDirectory(directory, roots) {
     }
     return roots.has(currentPath) ? currentPath : null;
 }
-function getProjectUsingESLintConfig(configFilePath, projectRoot, eslintVersion, options, context, pmc, tsconfigChainOutsideProjectRoot) {
+function getProjectUsingESLintConfig(configFilePath, projectRoot, options, context, pmc, tsconfigChainOutsideProjectRoot) {
     const rootEslintConfig = [
         config_file_1.baseEsLintConfigFile,
         ...config_file_1.BASE_ESLINT_CONFIG_FILENAMES,
@@ -275,10 +273,10 @@ function getProjectUsingESLintConfig(configFilePath, projectRoot, eslintVersion,
         eslintConfigs.unshift(rootEslintConfig);
     }
     return {
-        targets: buildEslintTargets(eslintConfigs, eslintVersion, projectRoot, context.workspaceRoot, options, pmc, standaloneSrcPath, tsconfigChainOutsideProjectRoot),
+        targets: buildEslintTargets(eslintConfigs, projectRoot, context.workspaceRoot, options, pmc, standaloneSrcPath, tsconfigChainOutsideProjectRoot),
     };
 }
-function buildEslintTargets(eslintConfigs, eslintVersion, projectRoot, workspaceRoot, options, pmc, standaloneSrcPath, tsconfigChainOutsideProjectRoot = []) {
+function buildEslintTargets(eslintConfigs, projectRoot, workspaceRoot, options, pmc, standaloneSrcPath, tsconfigChainOutsideProjectRoot = []) {
     const isRootProject = projectRoot === '.';
     const targets = {};
     const targetConfig = {
@@ -315,13 +313,12 @@ function buildEslintTargets(eslintConfigs, eslintVersion, projectRoot, workspace
             },
         },
     };
-    // Always set the environment variable to ensure that the ESLint CLI can run on eslint v8 and v9
+    // Supported ESLint versions (v9+) default to flat config, so only set the env
+    // var when the workspace still uses eslintrc, to force the legacy loader.
     const useFlatConfig = eslintConfigs.some((config) => (0, config_file_1.isFlatConfig)(config));
-    // Flat config is default for 9.0.0+
-    const defaultSetting = (0, semver_1.gte)(eslintVersion, '9.0.0');
-    if (useFlatConfig !== defaultSetting) {
+    if (!useFlatConfig) {
         targetConfig.options.env = {
-            ESLINT_USE_FLAT_CONFIG: useFlatConfig ? 'true' : 'false',
+            ESLINT_USE_FLAT_CONFIG: 'false',
         };
     }
     targets[options.targetName] = targetConfig;

package/dist/src/utils/assert-supported-eslint-version.js

@@ -2,11 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertSupportedEslintVersion = assertSupportedEslintVersion;
 const internal_1 = require("@nx/devkit/internal");
-const deprecation_1 = require("./deprecation");
 const versions_1 = require("./versions");
 function assertSupportedEslintVersion(tree) {
     (0, internal_1.assertSupportedPackageVersion)(tree, 'eslint', versions_1.minSupportedEslintVersion);
-    if ((0, versions_1.getInstalledEslintMajorVersion)(tree) === 8) {
-        (0, deprecation_1.warnEslintV8Deprecation)();
-    }
 }

package/dist/src/utils/config-file.js

@@ -8,14 +8,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const flat_config_1 = require("./flat-config");
 exports.ESLINT_FLAT_CONFIG_FILENAMES = flat_config_1.eslintFlatConfigFilenames;
-exports.ESLINT_OLD_CONFIG_FILENAMES = [
-    '.eslintrc',
-    '.eslintrc.js',
-    '.eslintrc.cjs',
-    '.eslintrc.yaml',
-    '.eslintrc.yml',
-    '.eslintrc.json',
-];
+exports.ESLINT_OLD_CONFIG_FILENAMES = flat_config_1.eslintrcFilenames;
 exports.ESLINT_CONFIG_FILENAMES = [
     ...exports.ESLINT_OLD_CONFIG_FILENAMES,
     ...exports.ESLINT_FLAT_CONFIG_FILENAMES,

package/dist/src/utils/deprecation.d.ts

@@ -1,5 +1,3 @@
 export declare const ESLINT_EXECUTOR_DEPRECATION_MESSAGE = "The `@nx/eslint:lint` executor is deprecated and will be removed in Nx v24. Run `nx g @nx/eslint:convert-to-inferred` to migrate to the `@nx/eslint/plugin` inferred targets. See https://nx.dev/docs/guides/tasks--caching/convert-to-inferred for details.";
 export declare function warnEslintExecutorDeprecation(): void;
 export declare function warnEslintExecutorGenerating(): void;
-export declare const ESLINT_V8_DEPRECATION_MESSAGE = "Support for ESLint v8 is deprecated and will be removed in Nx v24. Please upgrade to ESLint v9.";
-export declare function warnEslintV8Deprecation(): void;