@kirill.konshin/lint 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +137 -18
- package/configs/base.js +98 -0
- package/configs/imports.js +162 -0
- package/configs/next.js +179 -0
- package/configs/nx.js +40 -0
- package/configs/prettier.js +21 -0
- package/configs/promise.js +21 -0
- package/configs/storybook.js +15 -0
- package/configs/tailwind.js +72 -0
- package/configs/testing.js +136 -0
- package/configs/turbo.js +29 -0
- package/configs/typescriptTypeAware.js +109 -0
- package/configs/unicorn.js +47 -0
- package/index.d.ts +241 -0
- package/index.js +114 -616
- package/lib.js +250 -0
- package/package.json +17 -3
- package/rules/tailwind.md +17 -0
- package/rules/testing.md +5 -4
- package/skills/lint-repo.md +2 -2
- package/ruleTestColocation.js +0 -50
package/README.md
CHANGED
|
@@ -24,33 +24,58 @@ node-linker=hoisted
|
|
|
24
24
|
`eslint.config.mjs`:
|
|
25
25
|
|
|
26
26
|
```js
|
|
27
|
-
import {
|
|
28
|
-
import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
|
|
27
|
+
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
29
28
|
|
|
30
|
-
export default
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
29
|
+
export default defineLintConfig(); // every tool integration auto-detected
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Every tool integration — Next.js, Nx, Turborepo, Storybook, Jest, Vitest, Tailwind — is auto-detected (the detection results are exported as `has*` booleans for debugging). Pass options (JSDoc-typed, see `LintOptions` in `index.js`) to force any of them on/off or to supply tool-specific settings:
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
export default defineLintConfig({
|
|
36
|
+
defaultIgnore: { importMetaUrl: import.meta.url }, // .gitignore + .prettierignore as ESLint ignores
|
|
37
|
+
next: { rootDir: 'path/to/next-app' }, // an options object means ON + settings; auto-detected when omitted
|
|
38
|
+
tailwind: true, // force ON when detection misses it
|
|
39
|
+
turbo: false, // force OFF
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `undefined` (default) — auto-detect
|
|
44
|
+
- `true` or an options object — force ON. Detection probes resolve from this package's install location, so in a monorepo where a tool lives only in **leaf** packages (not the root `package.json`) detection can miss it — force the flag in that case
|
|
45
|
+
- `false` — force OFF
|
|
46
|
+
- in the object form `enabled` defaults to `true` — providing options implies turning the tool on; set `enabled: false` to force OFF while keeping the other options in place (e.g. `tailwind: { enabled: false, cssConfigPath: '...' }`)
|
|
47
|
+
|
|
48
|
+
`defaultIgnore` and `typeAware` have nothing to auto-detect, so they are OFF unless set. `defaultIgnore` converts the `.gitignore` and `.prettierignore` sitting next to your config file (both must exist) into ESLint ignores — it needs your `import.meta.url`, so `defaultIgnore: true` alone is a hard error.
|
|
49
|
+
|
|
50
|
+
`next.rootDir` is auto-detected when omitted: the directories containing a `next.config.*`. None found → the setting is simply left out (it's optional); several apps → all of them as an array.
|
|
51
|
+
|
|
52
|
+
All file scans (Tailwind entry, `next.config.*`) and `nx.json` detection are anchored to the **workspace root**, not cwd — linting from inside a package (lint-staged, IDE, `yarn workspace x lint`) still sees the whole repo. The root is detected by asking the package manager (env: Yarn Berry `PROJECT_CWD`, npm `npm_config_local_prefix`; CLIs: `pnpm root -w`, Yarn Berry via `yarn node`, `npm prefix`), falling back to a lockfile walk bounded by `.git`; `findWorkspaceRoot` is exported for debugging alongside the `has*` flags. Yarn 1 (classic) provides neither a root env nor a root command — classic workspaces resolve via `npm prefix` (same package.json `workspaces` field) or the yarn.lock walk.
|
|
53
|
+
|
|
54
|
+
Options can also be produced by a (possibly async) function: `defineLintConfig(() => ({ tailwind: true }))`.
|
|
55
|
+
|
|
56
|
+
`defineLintConfig` returns a `Promise` — ESLint natively awaits a Promise default export, so the plain form above just works. To compose with your own blocks, `await` it:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
import { defineLintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
|
|
60
|
+
|
|
61
|
+
export default [
|
|
62
|
+
...(await defineLintConfig({ defaultIgnore: { importMetaUrl: import.meta.url } })),
|
|
43
63
|
{
|
|
44
64
|
name: 'Custom rules',
|
|
45
65
|
rules: {
|
|
46
66
|
// overrides
|
|
47
67
|
},
|
|
48
68
|
},
|
|
49
|
-
includeIgnoreFile(import.meta.url, '.
|
|
50
|
-
|
|
51
|
-
]);
|
|
69
|
+
includeIgnoreFile(import.meta.url, '.customignore'), // extra ignore files beyond defaultIgnore
|
|
70
|
+
];
|
|
52
71
|
```
|
|
53
72
|
|
|
73
|
+
**Every** block lives in a themed `configs/*.js` file and is exported as a standalone function for manual composition (and easy testing/mocking), in the order `defineLintConfig` applies them — blocks from the same file stay consecutive, which matters inside a family (Next: base config → the TS wiring stemming from it → overrides → settings): `baseConfig` (JS recommended + global ignores + globals + core-rule overrides), `defaultIgnoreConfig`, `nextConfig`, `typescriptOverridesConfig`, `nextOverridesConfig`, `reactSettingsConfig`, `prettierConfig`, `storybookConfig`, `typeAwareConfig` (off by default — see [Type-aware rules](#type-aware-rules); ordered before the import blocks so its naming-convention rule loses to the default-export relaxation), `importXConfig` (includes the default-export relaxation for conventional files), `importSortConfig`, `unusedImportsConfig`, `promiseConfig`, `unicornConfig`, `turboConfig`, `tailwindConfig`, `nxConfig`, `jestConfig`, `vitestConfig`, `testConfig`.
|
|
74
|
+
|
|
75
|
+
Tool-gated functions take the same value as their `defineLintConfig` flag and gate themselves (`tailwindConfig(true)`, `nxConfig(false)` → `[]`, `tailwindConfig({ cssConfigPath })`). `nextConfig` is a composite: `nextBaseConfig` (the pure Next blocks, also exported) when Next is enabled, the `reactConfig` fallback otherwise — both are exported for direct use too.
|
|
76
|
+
|
|
77
|
+
The package ships hand-written types (`index.d.ts`) that pull real types from the underlying packages — `Linter.Config` from `eslint`, `PluginSettings` from `eslint-plugin-tailwindcss`, `prettier`'s `Config`, `lint-staged`'s `Configuration` — so `defineLintConfig` options and all exports are fully typed in `eslint.config.mjs` (via editor inference) and `eslint.config.ts`.
|
|
78
|
+
|
|
54
79
|
`.prettierrc.mjs`:
|
|
55
80
|
|
|
56
81
|
```js
|
|
@@ -104,6 +129,42 @@ indent_style = tab
|
|
|
104
129
|
}
|
|
105
130
|
```
|
|
106
131
|
|
|
132
|
+
### Tailwind CSS rules
|
|
133
|
+
|
|
134
|
+
When Tailwind is enabled — auto-detected via `tailwindcss` (v4+) being installed, or forced with `tailwind: true` — the config enables [`eslint-plugin-tailwindcss`](https://github.com/francoismassart/eslint-plugin-tailwindcss) recommended rules. The plugin **must** be able to resolve the Tailwind entry CSS — it hard-crashes lint (ENOENT) otherwise — so the entry is auto-detected: the workspace is scanned for `*.css` files containing `@import "tailwindcss"` (up to five directory levels below the workspace root — covers `packages/<x>/src/styles` — skipping dot dirs, `node_modules`, build outputs like `dist`/`.next`, and everything in `.gitignore`).
|
|
135
|
+
|
|
136
|
+
- Exactly **one** entry found → rules enable automatically with it (added as a standalone config block, easy to override).
|
|
137
|
+
- **Zero or several** entries:
|
|
138
|
+
- auto-detected → nothing is added (inert); pass the entry explicitly (below)
|
|
139
|
+
- forced (`tailwind: true`) → **hard error** — you explicitly asked for Tailwind linting, so a silent skip would be a lie
|
|
140
|
+
- An explicit entry always wins over the scan:
|
|
141
|
+
|
|
142
|
+
```js
|
|
143
|
+
export default defineLintConfig({
|
|
144
|
+
tailwind: {
|
|
145
|
+
cssConfigPath: './src/styles/tailwind.css', // relative to the package root
|
|
146
|
+
},
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Type-aware rules (optional, disabled by default for performance)
|
|
151
|
+
|
|
152
|
+
Off by default (typed linting is slow); enable with `typeAware: true` or an options object.
|
|
153
|
+
|
|
154
|
+
Config files living outside any tsconfig `include` (`vite.config.ts`, `.storybook/main.ts`, …) need typescript-eslint's `allowDefaultProject` — it has **no default** here, and upstream forbids `**` in its patterns, so either spell out each directory level or generate the exact file list with the exported `scanWorkspace` (workspace-root-anchored, `.gitignore`- and build-output-aware; its absolute paths are relativized against `tsconfigRootDir` automatically):
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint';
|
|
158
|
+
|
|
159
|
+
export default defineLintConfig({
|
|
160
|
+
typeAware: {
|
|
161
|
+
allowDefaultProject: scanWorkspace('{vite,vitest}.config.ts'),
|
|
162
|
+
maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50, // defaults to allowDefaultProject.length when the list is given (typescript-eslint's own default is 8) - set it explicitly only when supplying multi-match globs
|
|
163
|
+
tsconfigRootDir: '...', // defaults to the detected workspace root
|
|
164
|
+
},
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
107
168
|
### IDEA settings
|
|
108
169
|
|
|
109
170
|
- Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
|
|
@@ -185,12 +246,70 @@ paths:
|
|
|
185
246
|
---
|
|
186
247
|
```
|
|
187
248
|
|
|
249
|
+
## Migration
|
|
250
|
+
|
|
251
|
+
### 0.2.x → 0.3.x
|
|
252
|
+
|
|
253
|
+
The default-exported config array was replaced by the `defineLintConfig()` factory (see [Settings](#settings)) — every tool integration is auto-detected and controlled via options instead of hand-written blocks.
|
|
254
|
+
|
|
255
|
+
Before (0.2.x):
|
|
256
|
+
|
|
257
|
+
```js
|
|
258
|
+
import { defineConfig } from 'eslint/config';
|
|
259
|
+
import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
|
|
260
|
+
|
|
261
|
+
export default defineConfig([
|
|
262
|
+
...customConfig,
|
|
263
|
+
{
|
|
264
|
+
files: [`**/*.${tsExts}`],
|
|
265
|
+
plugins: { next: nextPlugin },
|
|
266
|
+
settings: { next: { rootDir: 'path/to/next-app' } },
|
|
267
|
+
},
|
|
268
|
+
{ name: 'Custom rules', rules: {} },
|
|
269
|
+
includeIgnoreFile(import.meta.url, '.gitignore'),
|
|
270
|
+
includeIgnoreFile(import.meta.url, '.prettierignore'),
|
|
271
|
+
]);
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
After (0.3.x):
|
|
275
|
+
|
|
276
|
+
```js
|
|
277
|
+
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
278
|
+
|
|
279
|
+
export default [
|
|
280
|
+
...(await defineLintConfig({
|
|
281
|
+
defaultIgnore: { importMetaUrl: import.meta.url },
|
|
282
|
+
next: { rootDir: 'path/to/next-app' },
|
|
283
|
+
})),
|
|
284
|
+
{ name: 'Custom rules', rules: {} },
|
|
285
|
+
];
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
- **Default export removed** — import `defineLintConfig` and call it. ESLint awaits the returned Promise, so a plain `export default defineLintConfig({...})` works when no extra blocks are needed
|
|
289
|
+
- **Manual `settings.next.rootDir` block** → `next: { rootDir }` option — or nothing at all: it is auto-detected from `next.config.*` locations (several apps → array)
|
|
290
|
+
- **Scans are workspace-root-anchored** — the Tailwind entry / `next.config.*` scans and `nx.json` detection resolve the workspace root via the package manager instead of trusting cwd, so linting from inside a package behaves like linting from the root
|
|
291
|
+
- **Manual Tailwind block** (`settings.tailwindcss.cssConfigPath`) → `tailwind: { cssConfigPath }` option; `tailwind: true` without a resolvable entry CSS is now a **hard error** instead of a silent skip
|
|
292
|
+
- **`includeIgnoreFile(import.meta.url, '.gitignore' / '.prettierignore')` pair** → `defaultIgnore: { importMetaUrl: import.meta.url }` (`includeIgnoreFile` stays exported for extra ignore files)
|
|
293
|
+
- **`tailwindEntry` const removed** → call the exported `findTailwindEntry(ignores)` when needed
|
|
294
|
+
- **New:** every block is a composable exported `*Config()` function; gated ones accept `true` / `false` / an options object with optional `enabled` (defaults to `true` in the object form); `typeAware: true` enables the (slow) type-aware rules
|
|
295
|
+
- **`prettier` is now a declared (required) peer dependency** — it was always required by the setup, so no action needed in practice
|
|
296
|
+
- **TypeScript consumers get real types** — `index.d.ts` ships with the package (`LintOptions` and friends)
|
|
297
|
+
|
|
298
|
+
Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `has*` detection exports, plugin re-exports (`nxPlugin`, …) — is unchanged.
|
|
299
|
+
|
|
188
300
|
## Why raw JS (no build)
|
|
189
301
|
|
|
190
302
|
Deliberately plain ESM, **no TypeScript build**: the config is loaded by `eslint.config.mjs` and pre-commit `lint:staged` before anything is built, so a `dist/` `main` would force a build before the repo could lint — not worth it for a config package.
|
|
191
303
|
|
|
192
304
|
## Issues
|
|
193
305
|
|
|
306
|
+
- Package managers
|
|
307
|
+
- [ ] TODO verify the package end-to-end (workspace-root detection, Tailwind / `next.config.*` scans, `has*` capability probes, plugin resolution, `defineLintConfig` under a real lint run) with each manager:
|
|
308
|
+
- [x] Yarn Berry, node-modules linker — this repo, fully covered
|
|
309
|
+
- [ ] Yarn Berry **PnP** — entirely unverified: no `node_modules`, resolution/hoisting differs, `import.meta.resolve` probes and leaf-package detection may behave differently
|
|
310
|
+
- [ ] Yarn 1 (classic) — workspace-root detection verified in a scratch workspace (no root env, `npm prefix`/lockfile-walk path); full config unverified
|
|
311
|
+
- [ ] pnpm — workspace-root detection verified in a scratch workspace (`pnpm root -w`, no usable env); full config unverified
|
|
312
|
+
- [ ] npm — root probes verified (`npm_config_local_prefix`, workspace-aware `npm prefix`); full config unverified
|
|
194
313
|
- ESLint 9
|
|
195
314
|
- [x] https://github.com/microsoft/rushstack/issues/4635 Failed to patch ESLint because the calling module was not recognized
|
|
196
315
|
- [x] https://github.com/microsoft/rushstack/issues/4965 Failed to patch ESLint because the calling module was not recognized
|
package/configs/base.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { dirname, resolve } from 'node:path';
|
|
2
|
+
import { fileURLToPath } from 'node:url';
|
|
3
|
+
import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
|
|
4
|
+
import js from '@eslint/js';
|
|
5
|
+
import globals from 'globals';
|
|
6
|
+
|
|
7
|
+
import { asOptions, GLOBAL_IGNORES } from '../lib.js';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Core JS recommended rules, global ignores, browser + Node globals, and overrides of core ESLint
|
|
11
|
+
* rules.
|
|
12
|
+
*
|
|
13
|
+
* `eslint-config-next` already ignores `next-env.d.ts`, but only as a bare pattern ('next-env.d.ts'),
|
|
14
|
+
* which only matches at the config's own root - not when the Next app (and its generated
|
|
15
|
+
* next-env.d.ts) lives in a subdirectory, like demo/web-static/ here. It's auto-generated and
|
|
16
|
+
* explicitly marked "should not be edited", so exclude it recursively instead of just working
|
|
17
|
+
* around individual rules (its `///` reference directives otherwise trip multiline-comment-style,
|
|
18
|
+
* which would corrupt them if autofixed into a `/* *\/` block).
|
|
19
|
+
*
|
|
20
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
21
|
+
*/
|
|
22
|
+
export function baseConfig() {
|
|
23
|
+
return [
|
|
24
|
+
js.configs.recommended,
|
|
25
|
+
{
|
|
26
|
+
name: 'Global Ignores',
|
|
27
|
+
ignores: GLOBAL_IGNORES,
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
name: 'Globals',
|
|
31
|
+
languageOptions: {
|
|
32
|
+
globals: {
|
|
33
|
+
...globals.browser,
|
|
34
|
+
...globals.node,
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
name: 'ESLint overrides',
|
|
40
|
+
rules: {
|
|
41
|
+
'no-restricted-imports': [
|
|
42
|
+
'error',
|
|
43
|
+
{
|
|
44
|
+
paths: [
|
|
45
|
+
{
|
|
46
|
+
name: 'next/router',
|
|
47
|
+
message: 'Please use next/navigation instead of next/router',
|
|
48
|
+
},
|
|
49
|
+
],
|
|
50
|
+
},
|
|
51
|
+
],
|
|
52
|
+
// 'multiline-comment-style': ['warn', 'starred-block'],
|
|
53
|
+
'multiline-comment-style': 'off',
|
|
54
|
+
},
|
|
55
|
+
},
|
|
56
|
+
];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Convert an ignore file (`.gitignore`, `.prettierignore`, ...) into an ESLint ignores block,
|
|
61
|
+
* resolved next to the consumer's config file.
|
|
62
|
+
*
|
|
63
|
+
* @param {string} importMetaUrl `import.meta.url` of the consumer's `eslint.config.mjs`
|
|
64
|
+
* @param {string} ignoreFile
|
|
65
|
+
* @returns {import('eslint').Linter.Config}
|
|
66
|
+
*/
|
|
67
|
+
export function includeIgnoreFile(importMetaUrl, ignoreFile) {
|
|
68
|
+
// @see https://blog.linotte.dev/eslint-9-next-js-935c2b6d0371
|
|
69
|
+
return includeIgnoreFileCompat(resolve(dirname(fileURLToPath(importMetaUrl)), ignoreFile));
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** @typedef {import('../index.js').DefaultIgnoreOptions} DefaultIgnoreOptions Defined in index.d.ts. */
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* The conventional ignore setup of this toolkit: `.gitignore` + `.prettierignore` next to the
|
|
76
|
+
* consumer's config file, both converted into ESLint ignores via {@link includeIgnoreFile} (both
|
|
77
|
+
* files must exist - the prettier scripts in README use the same two).
|
|
78
|
+
*
|
|
79
|
+
* There is nothing to auto-detect here - the consumer's config file location can't be known - so
|
|
80
|
+
* the flag is off by default and enabling it without `importMetaUrl` is a hard error.
|
|
81
|
+
*
|
|
82
|
+
* @param {boolean | DefaultIgnoreOptions} [option] the defineLintConfig `defaultIgnore` flag
|
|
83
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
84
|
+
*/
|
|
85
|
+
export function defaultIgnoreConfig(option) {
|
|
86
|
+
const { enabled = false, importMetaUrl } = asOptions(option);
|
|
87
|
+
if (!enabled) return [];
|
|
88
|
+
|
|
89
|
+
if (!importMetaUrl) {
|
|
90
|
+
throw new Error(
|
|
91
|
+
'[@kirill.konshin/lint] `defaultIgnore` was enabled, but `importMetaUrl` was not provided - the ' +
|
|
92
|
+
'location of the consumer config file cannot be auto-detected. ' +
|
|
93
|
+
'Pass `defaultIgnore: { importMetaUrl: import.meta.url }`.',
|
|
94
|
+
);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
return [includeIgnoreFile(importMetaUrl, '.gitignore'), includeIgnoreFile(importMetaUrl, '.prettierignore')];
|
|
98
|
+
}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';
|
|
2
|
+
import importXPlugin, { createNodeResolver } from 'eslint-plugin-import-x';
|
|
3
|
+
import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
|
|
4
|
+
import unusedImportsPlugin from 'eslint-plugin-unused-imports';
|
|
5
|
+
|
|
6
|
+
import { tsExts } from '../lib.js';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Import linting via eslint-plugin-import-x: recommended rules + overrides + the default-export
|
|
10
|
+
* relaxation for files that legitimately default-export (framework/tooling conventions) - the
|
|
11
|
+
* latter makes no sense without `import-x/no-default-export`, so it is not a separate block.
|
|
12
|
+
*
|
|
13
|
+
* eslint-config-next already registers `eslint-plugin-import` under the 'import' key, and ESLint 10
|
|
14
|
+
* hard-errors ("Cannot redefine plugin") if a later config tries to reuse that same key with a
|
|
15
|
+
* different plugin instance. eslint-plugin-import-x is a drop-in replacement, registered under its
|
|
16
|
+
* own 'import-x' key instead (its own recommended config does this registration for us).
|
|
17
|
+
*
|
|
18
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
19
|
+
*/
|
|
20
|
+
export function importXConfig() {
|
|
21
|
+
return [
|
|
22
|
+
importXPlugin.configs['flat/recommended'],
|
|
23
|
+
{
|
|
24
|
+
name: 'eslint-plugin-import-x overrides',
|
|
25
|
+
settings: {
|
|
26
|
+
/*
|
|
27
|
+
* `createTypeScriptImportResolver` correctly resolves relative imports and simple TS path
|
|
28
|
+
* aliases, but NOT cross-workspace-package imports in this monorepo (e.g. `@kirill.konshin/node`)
|
|
29
|
+
* or subpath exports (e.g. `next/constants`) - verified empirically. That's why the
|
|
30
|
+
* resolution-dependent rules below are turned off rather than left on the recommended default.
|
|
31
|
+
*/
|
|
32
|
+
'import-x/resolver-next': [createTypeScriptImportResolver(), createNodeResolver()],
|
|
33
|
+
},
|
|
34
|
+
rules: {
|
|
35
|
+
/*
|
|
36
|
+
* Off because of the workspace/subpath resolution gaps above - re-enable per-project once
|
|
37
|
+
* resolution is confirmed reliable there (e.g. a single-app, non-monorepo consumer).
|
|
38
|
+
*/
|
|
39
|
+
'import-x/no-unresolved': 'off',
|
|
40
|
+
'import-x/named': 'off',
|
|
41
|
+
'import-x/namespace': 'off',
|
|
42
|
+
'import-x/default': 'off',
|
|
43
|
+
'import-x/export': 'off',
|
|
44
|
+
/*
|
|
45
|
+
* Same resolution caveat, and also the two most expensive rules in the recommended set
|
|
46
|
+
* (they parse every imported module looking for its named exports).
|
|
47
|
+
*/
|
|
48
|
+
'import-x/no-named-as-default': 'off',
|
|
49
|
+
'import-x/no-named-as-default-member': 'off',
|
|
50
|
+
'import-x/no-default-export': 'warn', // relaxed for conventional files below
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
name: 'Default export overrides',
|
|
55
|
+
// files that legitimately default-export (framework/tooling conventions)
|
|
56
|
+
files: [
|
|
57
|
+
'**/*.config.*',
|
|
58
|
+
`**/*.stories.${tsExts}`,
|
|
59
|
+
`**/.storybook/main.${tsExts}`,
|
|
60
|
+
`**/.storybook/preview.${tsExts}`,
|
|
61
|
+
'**/.lintstagedrc*',
|
|
62
|
+
'**/.prettierrc*',
|
|
63
|
+
`**/App.${tsExts}`,
|
|
64
|
+
`**/index.${tsExts}`,
|
|
65
|
+
`**/main.${tsExts}`,
|
|
66
|
+
'**/*.d.ts',
|
|
67
|
+
`**/default.${tsExts}`,
|
|
68
|
+
`**/error.${tsExts}`,
|
|
69
|
+
`**/forbidden.${tsExts}`,
|
|
70
|
+
`**/global-error.${tsExts}`,
|
|
71
|
+
`**/layout.${tsExts}`,
|
|
72
|
+
`**/loading.${tsExts}`,
|
|
73
|
+
`**/not-found.${tsExts}`,
|
|
74
|
+
`**/page.${tsExts}`,
|
|
75
|
+
`**/template.${tsExts}`,
|
|
76
|
+
`**/unauthorized.${tsExts}`,
|
|
77
|
+
`**/apple-icon.${tsExts}`,
|
|
78
|
+
`**/icon.${tsExts}`,
|
|
79
|
+
`**/manifest.${tsExts}`,
|
|
80
|
+
`**/opengraph-image.${tsExts}`,
|
|
81
|
+
`**/robots.${tsExts}`,
|
|
82
|
+
`**/sitemap.${tsExts}`,
|
|
83
|
+
`**/twitter-image.${tsExts}`,
|
|
84
|
+
],
|
|
85
|
+
rules: {
|
|
86
|
+
/*
|
|
87
|
+
* Stories always default-export `meta`, and story exports (`Default`, `WithArgs`, ...) are PascalCase by
|
|
88
|
+
* Storybook's own convention, which the general rules disallow. The stray naming-convention entry is
|
|
89
|
+
* deliberately out of place here - the rule itself lives in typescriptTypeAware.js, which
|
|
90
|
+
* defineLintConfig orders BEFORE this block precisely so this exemption wins (flat config is
|
|
91
|
+
* last-wins).
|
|
92
|
+
*/
|
|
93
|
+
'import-x/no-default-export': 'off',
|
|
94
|
+
'@typescript-eslint/naming-convention': 'off',
|
|
95
|
+
},
|
|
96
|
+
},
|
|
97
|
+
];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Deterministic import ordering.
|
|
102
|
+
*
|
|
103
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
104
|
+
*/
|
|
105
|
+
export function importSortConfig() {
|
|
106
|
+
return [
|
|
107
|
+
{
|
|
108
|
+
name: 'eslint-plugin-simple-import-sort',
|
|
109
|
+
files: [`**/*.${tsExts}`],
|
|
110
|
+
plugins: { 'simple-import-sort': simpleImportSortPlugin },
|
|
111
|
+
rules: {
|
|
112
|
+
/*
|
|
113
|
+
* Side-effect imports (polyfills, CSS) ARE sorted into their group; the sorter only
|
|
114
|
+
* preserves the relative order of multiple side-effect imports that land in the SAME
|
|
115
|
+
* group (so order-dependent side effects stay put). Non-import code between imports
|
|
116
|
+
* splits them into independently-sorted chunks (standard simple-import-sort behavior).
|
|
117
|
+
*/
|
|
118
|
+
'simple-import-sort/imports': [
|
|
119
|
+
'error',
|
|
120
|
+
{
|
|
121
|
+
groups: [
|
|
122
|
+
// 1. Polyfills - side-effect imports that must run first
|
|
123
|
+
['^\\u0000.*(polyfill|core-js|regenerator-runtime|whatwg-fetch|@vitest/web-worker)'],
|
|
124
|
+
// 2. React
|
|
125
|
+
['^react(-dom)?(/|$)'],
|
|
126
|
+
// 3. Third-party packages (node: builtins + npm packages)
|
|
127
|
+
['^node:', '^@?\\w'],
|
|
128
|
+
// 4. Local imports - path aliases then relative
|
|
129
|
+
['^@/', '^\\.'],
|
|
130
|
+
// 5. CSS/styles from libraries (side-effect, package path)
|
|
131
|
+
['^\\u0000@?\\w'],
|
|
132
|
+
// 6. Local CSS/styles (side-effect, relative path)
|
|
133
|
+
['^\\u0000'],
|
|
134
|
+
],
|
|
135
|
+
},
|
|
136
|
+
],
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
];
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Autofixable removal of unused imports.
|
|
144
|
+
*
|
|
145
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
146
|
+
*/
|
|
147
|
+
export function unusedImportsConfig() {
|
|
148
|
+
return [
|
|
149
|
+
{
|
|
150
|
+
name: 'eslint-plugin-unused-imports',
|
|
151
|
+
plugins: { 'unused-imports': unusedImportsPlugin },
|
|
152
|
+
rules: {
|
|
153
|
+
/*
|
|
154
|
+
* Unlike `@typescript-eslint/no-unused-vars/core` `no-unused-vars`, this rule is
|
|
155
|
+
* autofixable - `--fix` deletes the unused import specifier (or the whole import
|
|
156
|
+
* statement if nothing from it is used) instead of just reporting it.
|
|
157
|
+
*/
|
|
158
|
+
'unused-imports/no-unused-imports': 'error',
|
|
159
|
+
},
|
|
160
|
+
},
|
|
161
|
+
];
|
|
162
|
+
}
|
package/configs/next.js
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { dirname } from 'node:path';
|
|
2
|
+
import nextTs from 'eslint-config-next/typescript';
|
|
3
|
+
import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
|
|
4
|
+
import reactPlugin from 'eslint-plugin-react';
|
|
5
|
+
import reactHooksPlugin from 'eslint-plugin-react-hooks';
|
|
6
|
+
|
|
7
|
+
import { asOptions, GLOBAL_IGNORES, hasNext, scanWorkspace, tsExts } from '../lib.js';
|
|
8
|
+
|
|
9
|
+
// lazy so consumers without Next don't pay the load cost - re-exported from index.js
|
|
10
|
+
export const nextPlugin = hasNext ? (await import('@next/eslint-plugin-next')).default : null;
|
|
11
|
+
|
|
12
|
+
/** @typedef {import('../index.js').NextOptions} NextOptions Defined in index.d.ts. */
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Auto-find Next.js app roots: every directory below the workspace root containing a
|
|
16
|
+
* `next.config.*` (scanned like the Tailwind entry - see `scanWorkspace`).
|
|
17
|
+
*
|
|
18
|
+
* @param {string[]} ignores glob patterns to skip
|
|
19
|
+
* @returns {string[]} absolute directories
|
|
20
|
+
*/
|
|
21
|
+
export function findNextRoots(ignores) {
|
|
22
|
+
// Set: a dir can hold several matches (next.config.js + next.config.ts mid-migration);
|
|
23
|
+
// sorted so the emitted settings block is deterministic across filesystems
|
|
24
|
+
return [...new Set(scanWorkspace('next.config.*', ignores).map((file) => dirname(file)))].sort();
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Next.js blocks: the whole `eslint-config-next` flat config, plus `settings.next.rootDir`.
|
|
29
|
+
*
|
|
30
|
+
* `rootDir` is auto-detected via {@link findNextRoots} when omitted: zero apps found → no settings
|
|
31
|
+
* block (the setting is optional and the plugin works without it - NOT an error, unlike the
|
|
32
|
+
* Tailwind entry); one or several → ALL of them (`settings.next.rootDir` accepts an array -
|
|
33
|
+
* pointing at just one app would break linting of the others).
|
|
34
|
+
*
|
|
35
|
+
* `eslint-config-next`'s own parser module does `require('next/dist/compiled/babel/eslint-parser')` -
|
|
36
|
+
* a file INSIDE the `next` package itself - so merely *importing* `eslint-config-next` crashes if
|
|
37
|
+
* `next` isn't installed at all (verified empirically: it throws "Cannot find module
|
|
38
|
+
* 'next/dist/compiled/babel/eslint-parser'" the instant the module loads). Hence the lazy import
|
|
39
|
+
* here; when the block is forced on without `next` around, that error IS the failure mode.
|
|
40
|
+
*
|
|
41
|
+
* @param {NextOptions} [options]
|
|
42
|
+
* @returns {Promise<import('eslint').Linter.Config[]>}
|
|
43
|
+
*/
|
|
44
|
+
export async function nextBaseConfig({ rootDir = findNextRoots(GLOBAL_IGNORES) } = {}) {
|
|
45
|
+
const next = (await import('eslint-config-next')).default;
|
|
46
|
+
return [
|
|
47
|
+
...next,
|
|
48
|
+
// eslint-config-next already registers the @next/next plugin, only the settings are needed
|
|
49
|
+
...(rootDir?.length ? [{ name: '@next/eslint-plugin-next settings', settings: { next: { rootDir } } }] : []),
|
|
50
|
+
];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Non-Next React projects - this config is also used for Vite+React apps - still want React/React
|
|
55
|
+
* Hooks/jsx-a11y linting, which `eslint-config-next` normally provides but only via the Next-specific
|
|
56
|
+
* parser. Cover the same ground directly instead, with whatever parser is already active
|
|
57
|
+
* (typescript-eslint for .ts/.tsx via typescriptConfig, the default parser otherwise).
|
|
58
|
+
*
|
|
59
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
60
|
+
*/
|
|
61
|
+
export function reactConfig() {
|
|
62
|
+
return [
|
|
63
|
+
reactPlugin.configs.flat.recommended,
|
|
64
|
+
reactPlugin.configs.flat['jsx-runtime'],
|
|
65
|
+
reactHooksPlugin.configs.flat['recommended-latest'],
|
|
66
|
+
jsxA11yPlugin.flatConfigs.recommended,
|
|
67
|
+
];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Composite: {@link nextBaseConfig} when Next is enabled (auto-detected or forced via the flag),
|
|
72
|
+
* the {@link reactConfig} fallback otherwise.
|
|
73
|
+
*
|
|
74
|
+
* @param {boolean | NextOptions} [option] the defineLintConfig `next` flag
|
|
75
|
+
* @returns {Promise<import('eslint').Linter.Config[]>}
|
|
76
|
+
*/
|
|
77
|
+
export async function nextConfig(option) {
|
|
78
|
+
const { enabled = hasNext, ...options } = asOptions(option);
|
|
79
|
+
return enabled ? await nextBaseConfig(options) : reactConfig();
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* TypeScript blocks - lives here because the wiring stems from `eslint-config-next/typescript`
|
|
84
|
+
* (typescript-eslint recommended setup, useful with or without Next itself) + deliberate overrides
|
|
85
|
+
* of its rule set.
|
|
86
|
+
*
|
|
87
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
88
|
+
*/
|
|
89
|
+
export function typescriptOverridesConfig() {
|
|
90
|
+
return [
|
|
91
|
+
...nextTs,
|
|
92
|
+
{
|
|
93
|
+
name: '@typescript-eslint overrides',
|
|
94
|
+
files: [`**/*.${tsExts}`],
|
|
95
|
+
rules: {
|
|
96
|
+
'@typescript-eslint/explicit-module-boundary-types': 'off',
|
|
97
|
+
'@typescript-eslint/no-empty-function': 'off',
|
|
98
|
+
'@typescript-eslint/no-explicit-any': 'off',
|
|
99
|
+
'@typescript-eslint/no-require-imports': 'off',
|
|
100
|
+
'@typescript-eslint/no-unused-vars': 'off', // superseded by 'unused-imports/no-unused-imports', which is actually autofixable
|
|
101
|
+
'@typescript-eslint/consistent-type-definitions': ['error', 'type'],
|
|
102
|
+
'@typescript-eslint/consistent-type-imports': [
|
|
103
|
+
'error',
|
|
104
|
+
{ prefer: 'type-imports', fixStyle: 'inline-type-imports' },
|
|
105
|
+
],
|
|
106
|
+
'@typescript-eslint/ban-ts-comment': [
|
|
107
|
+
'error',
|
|
108
|
+
{
|
|
109
|
+
'ts-expect-error': 'allow-with-description',
|
|
110
|
+
'ts-ignore': true,
|
|
111
|
+
'ts-nocheck': true,
|
|
112
|
+
'ts-check': false,
|
|
113
|
+
minimumDescriptionLength: 3,
|
|
114
|
+
},
|
|
115
|
+
],
|
|
116
|
+
/*
|
|
117
|
+
* `as const` is the mechanical half of "Prefer `as const` and `readonly` for immutable
|
|
118
|
+
* constants and objects" - the `readonly` half is a per-case judgment call (which objects
|
|
119
|
+
* deserve it), so that guidance stays in typescript.md instead of being lint-enforced here.
|
|
120
|
+
*/
|
|
121
|
+
'@typescript-eslint/prefer-as-const': 'error',
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
name: '@typescript-eslint declaration-file overrides',
|
|
126
|
+
files: ['**/*.d.ts'],
|
|
127
|
+
rules: {
|
|
128
|
+
/*
|
|
129
|
+
* `typeof import('pkg')` annotations are the standard mechanism in declaration files
|
|
130
|
+
* (tsc itself emits them when generating .d.ts) - the annotation ban of
|
|
131
|
+
* consistent-type-imports is meant for source files.
|
|
132
|
+
*/
|
|
133
|
+
'@typescript-eslint/consistent-type-imports': [
|
|
134
|
+
'error',
|
|
135
|
+
{ prefer: 'type-imports', fixStyle: 'inline-type-imports', disallowTypeAnnotations: false },
|
|
136
|
+
],
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
];
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Overrides of rules set by `eslint-config-next`. Always applied (not gated on Next): the
|
|
144
|
+
* jsx-a11y/react entries matter for {@link reactConfig} consumers too, and turning off rules of an
|
|
145
|
+
* unregistered plugin is harmless.
|
|
146
|
+
*
|
|
147
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
148
|
+
*/
|
|
149
|
+
export function nextOverridesConfig() {
|
|
150
|
+
return [
|
|
151
|
+
{
|
|
152
|
+
name: 'eslint-config-next overrides',
|
|
153
|
+
rules: {
|
|
154
|
+
'@next/next/no-html-link-for-pages': 'off',
|
|
155
|
+
'@next/next/no-img-element': 'off',
|
|
156
|
+
'import/no-anonymous-default-export': 'off', // overrides eslint-config-next's own default
|
|
157
|
+
'jsx-a11y/alt-text': 'off',
|
|
158
|
+
'react/prop-types': 'off', // ts does it statically
|
|
159
|
+
},
|
|
160
|
+
},
|
|
161
|
+
];
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* FIXME ESLint 10 + Next fix
|
|
166
|
+
* https://github.com/vercel/next.js/issues/89764
|
|
167
|
+
* https://gist.github.com/OscarGauss/1f305edf5b7c103bb2ee32ba479f4261
|
|
168
|
+
*
|
|
169
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
170
|
+
*/
|
|
171
|
+
export function reactSettingsConfig() {
|
|
172
|
+
return [
|
|
173
|
+
{
|
|
174
|
+
settings: {
|
|
175
|
+
react: { version: '19' },
|
|
176
|
+
},
|
|
177
|
+
},
|
|
178
|
+
];
|
|
179
|
+
}
|