feat(migration docs): update migration docs based on mc-fe migration

Author: ByronDWall

packages-backend/eslint-config-node/migrations/v27.md

@@ -142,6 +142,78 @@ The base `mcAppConfig` registers plugins for:
 
 If your override mixes rules from different plugins, split into separate config objects matching each plugin's file types (e.g., `react/` rules in `**/*.{js,jsx,tsx}`, `@typescript-eslint/` rules in `**/*.{ts,tsx}`, core rules in `**/*.{js,jsx,ts,tsx}`).
 
+#### Common mistake: catch-all file patterns with mixed plugin rules
+
+The natural instinct when converting a subdirectory `.eslintrc.cjs` is to put all the rules into a single config object targeting `**/*.{js,jsx,ts,tsx}`. This will fail because not every plugin is registered for every file type.
+
+```js
+// WRONG — will error on .ts files because `react` plugin is not registered for them
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: {
+    'no-console': 'warn',                                 // core — works on all
+    'react/jsx-sort-props': 'error',                       // react — NOT on .ts
+    '@typescript-eslint/consistent-type-imports': 'error', // ts — NOT on .js/.jsx
+  },
+}
+```
+
+Split into separate config objects, each matching the plugin's registered file types:
+
+```js
+// Core ESLint rules — all source files
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-console': 'warn' },
+},
+// React rules — only file types where the react plugin is registered
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,tsx}'],
+  rules: { 'react/jsx-sort-props': 'error' },
+},
+// TypeScript rules — only .ts and .tsx
+{
+  files: ['packages/my-app/src/**/*.{ts,tsx}'],
+  rules: { '@typescript-eslint/consistent-type-imports': 'error' },
+},
+```
+
+> **Tip**: When converting an existing `.eslintrc.cjs`, group its rules by which plugin they belong to, then create one config object per plugin group with the correct `files` pattern. Core ESLint rules (no plugin prefix) can target all file types.
+
+#### Common mistake: `no-unused-vars` duplication on TypeScript files
+
+The base `mcAppConfig` disables core `no-unused-vars` on `.ts`/`.tsx` files and replaces it with `@typescript-eslint/no-unused-vars`. If your subdirectory config re-enables the core `no-unused-vars` for all file types, both rules will fire on TypeScript files, producing duplicate errors.
+
+```js
+// WRONG — re-enables core no-unused-vars on .ts/.tsx where @typescript-eslint
+// version is already active from the base config
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+Scope core `no-unused-vars` overrides to JavaScript files only:
+
+```js
+// CORRECT — only overrides the core rule on files where it applies
+{
+  files: ['packages/my-app/src/**/*.{js,jsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+### Self-linting the config file
+
+The root `eslint.config.js` is itself a `.js` file in your project, so ESLint will lint it. Rules like `import/extensions` may error on `.cjs` requires. Add a self-override to avoid this:
+
+```js
+{
+  files: ['eslint.config.js'],
+  rules: { 'import/extensions': 'off' },
+},
+```
+
 ## Step 4: Update `package.json`
 
 ```diff
@@ -168,6 +240,27 @@ If you maintain custom ESLint rule plugins, update deprecated APIs:
 
 Also update the plugin's `peerDependencies` to `"eslint": "9.x"`.
 
+### `jest-runner-eslint` compatibility
+
+If using `jest-runner-eslint`, note that the `rules` key in `cliOptions` is not supported in flat config mode — move those rule overrides into `eslint.config.js` instead. You may also need a `pnpm.overrides` (or npm `overrides`) entry if the package's peer dependency still specifies ESLint 8:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "jest-runner-eslint>eslint": "^9.0.0"
+    }
+  }
+}
+```
+
+If the formatter path uses a bare directory import (e.g., `node_modules/eslint-formatter-pretty`), ESM module resolution will reject it. Change to an explicit file path:
+
+```diff
+- format: 'node_modules/eslint-formatter-pretty',
++ format: 'node_modules/eslint-formatter-pretty/index.js',
+```
+
 ## Step 5: Clean up
 
 - Delete **all** `.eslintrc.*` files (root and subdirectories)
@@ -187,11 +280,40 @@ Run eslint on at least one file from **each directory that had its own config**.
 
 ## Troubleshooting
 
-**"Definition for rule 'plugin/rule-name' was not found"**: Plugin not registered for that file type. Common case: stale `eslint-disable-next-line` comments for plugins not valid on that file type (e.g., `@typescript-eslint/...` in a `.js` file). **Fix**: remove the stale comment, or register the plugin for that file type.
+**"Definition for rule 'plugin/rule-name' was not found"**: This means a rule is referenced on a file type where its plugin isn't registered. Two common causes:
+
+1. **Config rules targeting wrong file types** — your subdirectory config has a catch-all `files` pattern like `**/*.{js,jsx,ts,tsx}` but includes rules from a plugin that isn't registered for all of those types. See "Plugin scoping" above for how to split by plugin.
+2. **Stale inline `eslint-disable` comments** — ESLint 8 silently ignored `eslint-disable` comments referencing rules from unregistered plugins. ESLint 9 treats them as errors. This surfaces pre-existing stale comments that were previously harmless (e.g., `// eslint-disable-next-line testing-library/no-render-in-setup` in a file that isn't matched by the `testing-library` plugin's file pattern, or `@typescript-eslint/...` in a `.js` file). **Fix**: remove the stale disable comment, or if the rule should apply, register the plugin for that file type.
 
 **"ReferenceError: module is not defined in ES module scope"**: Config file uses `module.exports` but nearest `package.json` has `"type": "module"`. **Fix**: rename to `.cjs` extension and update imports.
 
-**Jest globals (`describe`, `it`, `expect`) not defined**: The base config only injects Jest globals for `**/*.{spec,test}.*`. For other naming conventions (e.g. `*.visualspec.js`), add `languageOptions: { globals: { ...require('globals').jest } }` for those file patterns.
+**Jest globals (`describe`, `it`, `expect`) not defined**: The base config only injects Jest globals for `**/*.{spec,test}.*`. Other files that use Jest APIs need explicit globals. Common patterns that are easy to miss:
+
+- `__mocks__/` directories (at any depth)
+- `test-utils/` directories (helper modules used by tests)
+
+Add a config block for these:
+
+```js
+{
+  files: [
+    '**/__mocks__/**/*.{js,jsx,ts,tsx}',
+    '**/test-utils/**/*.{js,jsx,ts,tsx}',
+  ],
+  languageOptions: {
+    globals: {
+      jest: 'readonly',
+      expect: 'readonly',
+    },
+  },
+},
+```
+
+> **Note**: Use `**/__mocks__/**` (with leading `**/`), not `__mocks__/**`. The latter only matches a `__mocks__/` directory at the project root. Most projects have `__mocks__/` directories nested inside packages or `src/` directories.
+
+**Duplicate `no-unused-vars` errors on `.ts`/`.tsx` files**: The base config sets `@typescript-eslint/no-unused-vars` for TypeScript files and disables the core `no-unused-vars` there. If your subdirectory config re-enables `no-unused-vars` for `**/*.{js,jsx,ts,tsx}`, both rules fire on TypeScript files. **Fix**: scope `no-unused-vars` overrides to `**/*.{js,jsx}` only. See "Common mistake" above.
+
+**Lint errors in `eslint.config.js` itself**: The config file is a `.js` file in the project root, so ESLint lints it. Rules like `import/extensions` may error on `.cjs` requires. **Fix**: add a self-override: `{ files: ['eslint.config.js'], rules: { 'import/extensions': 'off' } }`.
 
 **"Cannot find module 'some-eslint-plugin'"**: Plugins must be installed as direct dependencies in flat config.
 

packages/eslint-config-mc-app/migrations/v27.md

@@ -142,6 +142,78 @@ The base `mcAppConfig` registers plugins for:
 
 If your override mixes rules from different plugins, split into separate config objects matching each plugin's file types (e.g., `react/` rules in `**/*.{js,jsx,tsx}`, `@typescript-eslint/` rules in `**/*.{ts,tsx}`, core rules in `**/*.{js,jsx,ts,tsx}`).
 
+#### Common mistake: catch-all file patterns with mixed plugin rules
+
+The natural instinct when converting a subdirectory `.eslintrc.cjs` is to put all the rules into a single config object targeting `**/*.{js,jsx,ts,tsx}`. This will fail because not every plugin is registered for every file type.
+
+```js
+// WRONG — will error on .ts files because `react` plugin is not registered for them
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: {
+    'no-console': 'warn',                                 // core — works on all
+    'react/jsx-sort-props': 'error',                       // react — NOT on .ts
+    '@typescript-eslint/consistent-type-imports': 'error', // ts — NOT on .js/.jsx
+  },
+}
+```
+
+Split into separate config objects, each matching the plugin's registered file types:
+
+```js
+// Core ESLint rules — all source files
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-console': 'warn' },
+},
+// React rules — only file types where the react plugin is registered
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,tsx}'],
+  rules: { 'react/jsx-sort-props': 'error' },
+},
+// TypeScript rules — only .ts and .tsx
+{
+  files: ['packages/my-app/src/**/*.{ts,tsx}'],
+  rules: { '@typescript-eslint/consistent-type-imports': 'error' },
+},
+```
+
+> **Tip**: When converting an existing `.eslintrc.cjs`, group its rules by which plugin they belong to, then create one config object per plugin group with the correct `files` pattern. Core ESLint rules (no plugin prefix) can target all file types.
+
+#### Common mistake: `no-unused-vars` duplication on TypeScript files
+
+The base `mcAppConfig` disables core `no-unused-vars` on `.ts`/`.tsx` files and replaces it with `@typescript-eslint/no-unused-vars`. If your subdirectory config re-enables the core `no-unused-vars` for all file types, both rules will fire on TypeScript files, producing duplicate errors.
+
+```js
+// WRONG — re-enables core no-unused-vars on .ts/.tsx where @typescript-eslint
+// version is already active from the base config
+{
+  files: ['packages/my-app/src/**/*.{js,jsx,ts,tsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+Scope core `no-unused-vars` overrides to JavaScript files only:
+
+```js
+// CORRECT — only overrides the core rule on files where it applies
+{
+  files: ['packages/my-app/src/**/*.{js,jsx}'],
+  rules: { 'no-unused-vars': 'error' },
+}
+```
+
+### Self-linting the config file
+
+The root `eslint.config.js` is itself a `.js` file in your project, so ESLint will lint it. Rules like `import/extensions` may error on `.cjs` requires. Add a self-override to avoid this:
+
+```js
+{
+  files: ['eslint.config.js'],
+  rules: { 'import/extensions': 'off' },
+},
+```
+
 ## Step 4: Update `package.json`
 
 ```diff
@@ -168,6 +240,27 @@ If you maintain custom ESLint rule plugins, update deprecated APIs:
 
 Also update the plugin's `peerDependencies` to `"eslint": "9.x"`.
 
+### `jest-runner-eslint` compatibility
+
+If using `jest-runner-eslint`, note that the `rules` key in `cliOptions` is not supported in flat config mode — move those rule overrides into `eslint.config.js` instead. You may also need a `pnpm.overrides` (or npm `overrides`) entry if the package's peer dependency still specifies ESLint 8:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "jest-runner-eslint>eslint": "^9.0.0"
+    }
+  }
+}
+```
+
+If the formatter path uses a bare directory import (e.g., `node_modules/eslint-formatter-pretty`), ESM module resolution will reject it. Change to an explicit file path:
+
+```diff
+- format: 'node_modules/eslint-formatter-pretty',
++ format: 'node_modules/eslint-formatter-pretty/index.js',
+```
+
 ## Step 5: Clean up
 
 - Delete **all** `.eslintrc.*` files (root and subdirectories)
@@ -187,11 +280,40 @@ Run eslint on at least one file from **each directory that had its own config**.
 
 ## Troubleshooting
 
-**"Definition for rule 'plugin/rule-name' was not found"**: Plugin not registered for that file type. Common case: stale `eslint-disable-next-line` comments for plugins not valid on that file type (e.g., `@typescript-eslint/...` in a `.js` file). **Fix**: remove the stale comment, or register the plugin for that file type.
+**"Definition for rule 'plugin/rule-name' was not found"**: This means a rule is referenced on a file type where its plugin isn't registered. Two common causes:
+
+1. **Config rules targeting wrong file types** — your subdirectory config has a catch-all `files` pattern like `**/*.{js,jsx,ts,tsx}` but includes rules from a plugin that isn't registered for all of those types. See "Plugin scoping" above for how to split by plugin.
+2. **Stale inline `eslint-disable` comments** — ESLint 8 silently ignored `eslint-disable` comments referencing rules from unregistered plugins. ESLint 9 treats them as errors. This surfaces pre-existing stale comments that were previously harmless (e.g., `// eslint-disable-next-line testing-library/no-render-in-setup` in a file that isn't matched by the `testing-library` plugin's file pattern, or `@typescript-eslint/...` in a `.js` file). **Fix**: remove the stale disable comment, or if the rule should apply, register the plugin for that file type.
 
 **"ReferenceError: module is not defined in ES module scope"**: Config file uses `module.exports` but nearest `package.json` has `"type": "module"`. **Fix**: rename to `.cjs` extension and update imports.
 
-**Jest globals (`describe`, `it`, `expect`) not defined**: The base config only injects Jest globals for `**/*.{spec,test}.*`. For other naming conventions (e.g. `*.visualspec.js`), add `languageOptions: { globals: { ...require('globals').jest } }` for those file patterns.
+**Jest globals (`describe`, `it`, `expect`) not defined**: The base config only injects Jest globals for `**/*.{spec,test}.*`. Other files that use Jest APIs need explicit globals. Common patterns that are easy to miss:
+
+- `__mocks__/` directories (at any depth)
+- `test-utils/` directories (helper modules used by tests)
+
+Add a config block for these:
+
+```js
+{
+  files: [
+    '**/__mocks__/**/*.{js,jsx,ts,tsx}',
+    '**/test-utils/**/*.{js,jsx,ts,tsx}',
+  ],
+  languageOptions: {
+    globals: {
+      jest: 'readonly',
+      expect: 'readonly',
+    },
+  },
+},
+```
+
+> **Note**: Use `**/__mocks__/**` (with leading `**/`), not `__mocks__/**`. The latter only matches a `__mocks__/` directory at the project root. Most projects have `__mocks__/` directories nested inside packages or `src/` directories.
+
+**Duplicate `no-unused-vars` errors on `.ts`/`.tsx` files**: The base config sets `@typescript-eslint/no-unused-vars` for TypeScript files and disables the core `no-unused-vars` there. If your subdirectory config re-enables `no-unused-vars` for `**/*.{js,jsx,ts,tsx}`, both rules fire on TypeScript files. **Fix**: scope `no-unused-vars` overrides to `**/*.{js,jsx}` only. See "Common mistake" above.
+
+**Lint errors in `eslint.config.js` itself**: The config file is a `.js` file in the project root, so ESLint lints it. Rules like `import/extensions` may error on `.cjs` requires. **Fix**: add a self-override: `{ files: ['eslint.config.js'], rules: { 'import/extensions': 'off' } }`.
 
 **"Cannot find module 'some-eslint-plugin'"**: Plugins must be installed as direct dependencies in flat config.