@kirill.konshin/lint 0.2.0 → 0.3.1
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 +202 -51
- package/configs/base.js +98 -0
- package/configs/imports.js +162 -0
- package/configs/nx.js +48 -0
- package/configs/prettier.js +21 -0
- package/configs/promise.js +21 -0
- package/configs/react.js +262 -0
- package/configs/storybook.js +26 -0
- package/configs/tailwind.js +100 -0
- package/configs/testing.js +158 -0
- package/configs/turbo.js +29 -0
- package/configs/typescriptTypeAware.js +110 -0
- package/configs/unicorn.js +47 -0
- package/index.d.ts +271 -0
- package/index.js +119 -610
- package/lib.js +412 -15
- package/package.json +10 -4
- package/rules/tailwind.md +12 -14
- package/rules/testing.md +5 -4
- package/skills/lint-repo.md +2 -2
- package/findTailwindEntry.js +0 -46
- package/ruleTestColocation.js +0 -50
package/README.md
CHANGED
|
@@ -17,41 +17,114 @@ auto-install-peers=true
|
|
|
17
17
|
node-linker=hoisted
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
## ESLint
|
|
21
|
-
|
|
22
|
-
### Settings
|
|
20
|
+
## ESLint
|
|
23
21
|
|
|
24
22
|
`eslint.config.mjs`:
|
|
25
23
|
|
|
24
|
+
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:
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
{
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
},
|
|
29
|
+
// every tool integration auto-detected
|
|
30
|
+
export default defineLintConfig({
|
|
31
|
+
defaultIgnore: { importMetaUrl: import.meta.url }, // .gitignore + .prettierignore as ESLint ignores
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Config can be extended, `defineLintConfig` returns a `Promise` (natively awaited by ESLint), to compose with your own blocks, `await` it:
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
import { defineLintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
|
|
39
|
+
|
|
40
|
+
export default [
|
|
41
|
+
...(await defineLintConfig({ defaultIgnore: { importMetaUrl: import.meta.url } })),
|
|
43
42
|
{
|
|
44
43
|
name: 'Custom rules',
|
|
45
44
|
rules: {
|
|
46
45
|
// overrides
|
|
47
46
|
},
|
|
48
47
|
},
|
|
49
|
-
includeIgnoreFile(import.meta.url, '.
|
|
50
|
-
|
|
51
|
-
]);
|
|
48
|
+
includeIgnoreFile(import.meta.url, '.customignore'), // extra ignore files beyond defaultIgnore
|
|
49
|
+
];
|
|
52
50
|
```
|
|
53
51
|
|
|
54
|
-
|
|
52
|
+
### Full Config Example
|
|
53
|
+
|
|
54
|
+
Default behavior in the comments, all tools are optional (see [Detection](#detection)). Enable/disable tools using:
|
|
55
|
+
|
|
56
|
+
- `undefined` (default) — auto-detect, see [Detection](#detection)
|
|
57
|
+
- `true` — force ON (use when detection misses a tool, can be useful to see the error why tool is missing)
|
|
58
|
+
- `false` — force OFF
|
|
59
|
+
- `{ /* tool options *./ }` — object configuration implies `enabled: true` even if omitted; set `enabled: false` to force OFF while keeping the other options in place, see example
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint';
|
|
63
|
+
|
|
64
|
+
// function form shown
|
|
65
|
+
export default defineLintConfig(() => ({
|
|
66
|
+
// enabled (default true) = tools are ON unless said otherwise;
|
|
67
|
+
// strict (default false) = same-scope package probes only, no workspace scans and no symlink bridges
|
|
68
|
+
// `{ enabled: false, strict: true }` is ideal for per-package configs
|
|
69
|
+
detection: { enabled: true, strict: false }, // default
|
|
70
|
+
|
|
71
|
+
// ON by default; app roots auto-detected (next.config.*, package.json depending on next, src/{app,pages}/);
|
|
72
|
+
// can be force OFF; several apps auto-detect as array; pass the package root, not src
|
|
73
|
+
next: { rootDir: 'apps/web' }, // string or array
|
|
74
|
+
|
|
75
|
+
storybook: true, // force ON if detection failed
|
|
76
|
+
turbo: false, // force OFF
|
|
77
|
+
nx: true,
|
|
78
|
+
jest: false,
|
|
79
|
+
vitest: { enabled: true }, // object form implies ON; { enabled: false, ... } turns OFF keeping options
|
|
80
|
+
|
|
81
|
+
// ON by default; auto-detected single entry CSS; explicit path always wins over the scan
|
|
82
|
+
tailwind: { cssConfigPath: 'apps/web/src/app/index.css' },
|
|
83
|
+
|
|
84
|
+
// OFF by default
|
|
85
|
+
defaultIgnore: {
|
|
86
|
+
importMetaUrl: import.meta.url, // required, error if turned on via `defaultIgnore: true`
|
|
87
|
+
},
|
|
88
|
+
|
|
89
|
+
// OFF by default (slow) - see "Type-aware rules"
|
|
90
|
+
typeAware: {
|
|
91
|
+
allowDefaultProject: scanWorkspace('{vite,vitest}.config.ts'), // no default; absolute paths are relativized; ** globs are not supported
|
|
92
|
+
maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50, // defaults to the list length, (default 8), set it explicitly only when supplying multi-match globs
|
|
93
|
+
tsconfigRootDir: process.cwd(), // defaults to the detected workspace root
|
|
94
|
+
},
|
|
95
|
+
}));
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Per-package configs (monorepo)
|
|
99
|
+
|
|
100
|
+
ESLint 10 resolves the config **per linted file**: the nearest `eslint.config.mjs` up the tree wins **entirely** (no cascading/inheritance of rules). For full per-app Next/Tailwind linting in a multi-app monorepo, give each app its own config — either inherit the root and add overrides:
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
// apps/web/eslint.config.mjs
|
|
104
|
+
import rootConfig from '../../eslint.config.mjs';
|
|
105
|
+
|
|
106
|
+
export default [...(await rootConfig), { rules: { 'tailwindcss/no-custom-classname': 'off' } }];
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
…or simply call `defineLintConfig` again with the options this app needs:
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
// apps/web/eslint.config.mjs
|
|
113
|
+
import { fileURLToPath } from 'node:url';
|
|
114
|
+
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
115
|
+
|
|
116
|
+
export default defineLintConfig({
|
|
117
|
+
detection: { enabled: false, strict: true }, // fully explicit: this config only sees its own scope
|
|
118
|
+
// do not use workspace-wide auto-scan, provide exactly ONE from THIS leaf package
|
|
119
|
+
tailwind: { cssConfigPath: fileURLToPath(new URL('src/app/index.css', import.meta.url)) },
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
⚠️ Nearest-wins means root-only blocks (e.g. `defaultIgnore`, custom rules) do NOT apply to the subtree unless inherited or re-declared.
|
|
124
|
+
|
|
125
|
+
[Detection](#detection) runs against the **workspace root** even from a nested config, so per-app tool settings (`cssConfigPath`) should be explicit absolute paths — relative ones depend on the lint cwd.
|
|
126
|
+
|
|
127
|
+
## Prettier `.prettierrc.mjs`:
|
|
55
128
|
|
|
56
129
|
```js
|
|
57
130
|
import { prettier } from '@kirill.konshin/lint';
|
|
@@ -69,7 +142,7 @@ export default {
|
|
|
69
142
|
};
|
|
70
143
|
```
|
|
71
144
|
|
|
72
|
-
`.editorconfig`
|
|
145
|
+
## Editor Config `.editorconfig`
|
|
73
146
|
|
|
74
147
|
```editorconfig
|
|
75
148
|
root = true
|
|
@@ -104,29 +177,6 @@ indent_style = tab
|
|
|
104
177
|
}
|
|
105
178
|
```
|
|
106
179
|
|
|
107
|
-
### Tailwind CSS rules
|
|
108
|
-
|
|
109
|
-
When `tailwindcss` (v4+) is installed, the config auto-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 three directory levels deep — covers `packages/<x>/src` — skipping dot dirs, `node_modules`, and everything in `.gitignore`).
|
|
110
|
-
|
|
111
|
-
- Exactly **one** entry found → rules enable automatically with it (added as a standalone config block, easy to override).
|
|
112
|
-
- **Zero or several** entries → nothing is added; enable manually with a **mandatory** `settings.tailwindcss.cssConfigPath` in `eslint.config.mjs`:
|
|
113
|
-
|
|
114
|
-
```js
|
|
115
|
-
import customConfig, { tailwindPlugin } from '@kirill.konshin/lint';
|
|
116
|
-
|
|
117
|
-
export default defineConfig([
|
|
118
|
-
...customConfig,
|
|
119
|
-
{
|
|
120
|
-
...tailwindPlugin.configs.recommended,
|
|
121
|
-
settings: {
|
|
122
|
-
tailwindcss: {
|
|
123
|
-
cssConfigPath: './src/styles/tailwind.css', // relative to the package root
|
|
124
|
-
},
|
|
125
|
-
},
|
|
126
|
-
},
|
|
127
|
-
]);
|
|
128
|
-
```
|
|
129
|
-
|
|
130
180
|
### IDEA settings
|
|
131
181
|
|
|
132
182
|
- Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
|
|
@@ -197,7 +247,105 @@ In the project root, `lint-prepare`:
|
|
|
197
247
|
|
|
198
248
|
`init`/`update` refuse to run if `.claude/rules`, a skill target dir, or `CLAUDE.md` contains anything that isn't a symlink — this avoids silently overwriting files you created by hand. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
|
|
199
249
|
|
|
200
|
-
|
|
250
|
+
## Migration
|
|
251
|
+
|
|
252
|
+
### 0.2.x → 0.3.x
|
|
253
|
+
|
|
254
|
+
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.
|
|
255
|
+
|
|
256
|
+
Before (0.2.x):
|
|
257
|
+
|
|
258
|
+
```js
|
|
259
|
+
import { defineConfig } from 'eslint/config';
|
|
260
|
+
import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
|
|
261
|
+
|
|
262
|
+
export default defineConfig([
|
|
263
|
+
...customConfig,
|
|
264
|
+
{
|
|
265
|
+
files: [`**/*.${tsExts}`],
|
|
266
|
+
plugins: { next: nextPlugin },
|
|
267
|
+
settings: { next: { rootDir: 'path/to/next-app' } },
|
|
268
|
+
},
|
|
269
|
+
{ name: 'Custom rules', rules: {} },
|
|
270
|
+
includeIgnoreFile(import.meta.url, '.gitignore'),
|
|
271
|
+
includeIgnoreFile(import.meta.url, '.prettierignore'),
|
|
272
|
+
]);
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
After (0.3.x):
|
|
276
|
+
|
|
277
|
+
```js
|
|
278
|
+
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
279
|
+
|
|
280
|
+
export default [
|
|
281
|
+
...(await defineLintConfig({
|
|
282
|
+
defaultIgnore: { importMetaUrl: import.meta.url },
|
|
283
|
+
next: { rootDir: 'path/to/next-app' },
|
|
284
|
+
})),
|
|
285
|
+
{ name: 'Custom rules', rules: {} },
|
|
286
|
+
];
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- **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
|
|
290
|
+
- **Manual `settings.next.rootDir` block** → `next: { rootDir }` option — or nothing at all: it is auto-detected from `next.config.*` locations, `package.json`s depending on `next`, and `src/app`/`src/pages` trees (several apps → array)
|
|
291
|
+
- **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
|
|
292
|
+
- **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, and several entry CSS candidates are a hard error even in auto mode
|
|
293
|
+
- **`includeIgnoreFile(import.meta.url, '.gitignore' / '.prettierignore')` pair** → `defaultIgnore: { importMetaUrl: import.meta.url }` (`includeIgnoreFile` stays exported for extra ignore files)
|
|
294
|
+
- **`tailwindEntry` const removed** → call the exported `findTailwindEntry(ignores)` when needed
|
|
295
|
+
- **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
|
|
296
|
+
- **`prettier` is now a declared (required) peer dependency** — it was always required by the setup, so no action needed in practice
|
|
297
|
+
- **TypeScript consumers get real types** — `index.d.ts` ships with the package (`LintOptions` and friends)
|
|
298
|
+
|
|
299
|
+
Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `has*` detection exports, plugin re-exports (`nxPlugin`, …) — is unchanged.
|
|
300
|
+
|
|
301
|
+
## Development
|
|
302
|
+
|
|
303
|
+
### Why raw JS (no build)
|
|
304
|
+
|
|
305
|
+
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.
|
|
306
|
+
|
|
307
|
+
### Eslint
|
|
308
|
+
|
|
309
|
+
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`.
|
|
310
|
+
|
|
311
|
+
**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: `baseConfig` (JS recommended + global ignores + globals + core-rule overrides), `defaultIgnoreConfig`, `reactConfig` (the whole React family, see below), `prettierConfig`, `storybookConfig`, `typeAwareConfig` (off by default; 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`.
|
|
312
|
+
|
|
313
|
+
Tool-gated functions take the same value as their `defineLintConfig` flag and gate themselves (`tailwindConfig(true)`, `nxConfig(false)` → `[]`, `tailwindConfig({ cssConfigPath })`). `reactConfig(nextFlag, strict)` is the whole family in its load-bearing order — Next is just a shortcut to an opinionated React/TypeScript setup, so the TS wiring, overrides and settings apply no matter whether Next or plain React won: `nextConfig` (chooser: `nextBaseConfig` when Next is enabled, `reactBaseConfig` fallback otherwise) → `typescriptOverridesConfig` → `nextOverridesConfig` → `reactSettingsConfig` — all exported individually too.
|
|
314
|
+
|
|
315
|
+
### Detection
|
|
316
|
+
|
|
317
|
+
Due to limitations package visibility between leaf and root this package has to be creative to support config-free detection.
|
|
318
|
+
|
|
319
|
+
1. **Package probe** — `import.meta.resolve('<pkg>/package.json')` from this package's install location (`has<Pkg>` exported for debugging).
|
|
320
|
+
2. **Evidence scan** — tool config files below the **workspace root** (≤5 directory levels, skipping dot dirs, build outputs, and `.gitignore`d files; exported as `scanWorkspace`). Catches tools installed only in **leaf** packages, invisible to the probe (1). The workspace root itself comes from the package manager (env `PROJECT_CWD`/`npm_config_local_prefix` → CLIs `pnpm root -w`, Berry `yarn node`, `npm prefix` → lockfile walk bounded by `.git`; exported as `findWorkspaceRoot`), so linting from inside a package still sees the whole repo.
|
|
321
|
+
3. **Leaf bridge** — when a plugin needs the tool's package itself but it's only installed in a leaf, a symlink `<workspace root>/node_modules/<pkg>` → leaf install is created automatically (the next install prunes it, the next lint recreates it). Forcing a tool whose package resolves nowhere fails with an actionable error instead of a cryptic plugin crash.
|
|
322
|
+
4. **Yarn Berry PnP quirk** — leaf resolutions point inside the zip cache (virtual paths), so the bridge is skipped and leaf-only tools degrade gracefully (auto → off, forced → actionable error). Under PnP install the tools at the workspace root as well, keeping versions in sync with the leaves (e.g. the `"vitest": "$vitest"` version-alias hack); `next` documents its own monorepo ESLint setup.
|
|
323
|
+
|
|
324
|
+
| Option | Package | Evidence glob | When zero / many found |
|
|
325
|
+
| ----------- | ---------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
326
|
+
| `tailwind` | `tailwindcss`¹ | `*.css` with `@import "tailwindcss"` | needs exactly **one**: zero → off (forced → error), several → **always** error; set `cssConfigPath` |
|
|
327
|
+
| `next` | `next`¹ | `next.config.*`, `package.json` depending on `next`, `src/{app,pages}/` dir | zero → no `rootDir` (optional); many → all as array; or set `rootDir` (the package root, not `src`) |
|
|
328
|
+
| `storybook` | `storybook`¹ | `.storybook/main.*` | presence is enough |
|
|
329
|
+
| `jest` | `jest`¹ | `jest.config.*` | presence is enough |
|
|
330
|
+
| `vitest` | `vitest`¹ | `{vitest,vite}.config.*` | presence is enough |
|
|
331
|
+
| `nx` | (plugin bundled) | `nx.json` at the workspace root | — |
|
|
332
|
+
| `turbo` | `turbo` | package probe only | — |
|
|
333
|
+
|
|
334
|
+
¹ the plugins need the tool's package resolvable at lint time (`tailwindcss` for the theme-loading workers, `next` for `eslint-config-next`'s internal `require`s, `storybook` for its plugin's static import, `jest` for version sniffing) — covered by the leaf bridge above.
|
|
335
|
+
|
|
336
|
+
The machinery is controlled by the `detection` option (same toggle notation as the tools):
|
|
337
|
+
|
|
338
|
+
- `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (steps 2–3)
|
|
339
|
+
- `detection: { strict: true }` — only step 1 runs: the `has*` package probes **are** the strict detection (same-scope `import.meta.resolve`, no walking) — no workspace scans (2), no symlink bridges (3). Mandatory settings (`cssConfigPath`) must then be explicit, and `nx.json` is checked at **cwd** instead of the workspace root (`hasNx` is the only non-strict `has*`)
|
|
340
|
+
- `detection: { enabled: false, strict: true }` — fully explicit: tools on only when set, probes only
|
|
341
|
+
|
|
342
|
+
> `basePath: 'packages/xxx'` (ESLint ≥ 9.30) can scope a config object to a directory within a single root config, but it won't help with detection — `defineLintConfig` detects once, workspace-wide (e.g. Tailwind still demands exactly one entry CSS), so per-app settings would still have to be spelled out block by block; nested configs are the cleaner tool for this.
|
|
343
|
+
|
|
344
|
+
### Type-aware rules (optional, disabled by default for performance)
|
|
345
|
+
|
|
346
|
+
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):
|
|
347
|
+
|
|
348
|
+
### AI Rule file format
|
|
201
349
|
|
|
202
350
|
```yaml
|
|
203
351
|
---
|
|
@@ -208,12 +356,15 @@ paths:
|
|
|
208
356
|
---
|
|
209
357
|
```
|
|
210
358
|
|
|
211
|
-
## Why raw JS (no build)
|
|
212
|
-
|
|
213
|
-
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.
|
|
214
|
-
|
|
215
359
|
## Issues
|
|
216
360
|
|
|
361
|
+
- Package managers
|
|
362
|
+
- [ ] 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:
|
|
363
|
+
- [x] Yarn Berry, node-modules linker — this repo, fully covered
|
|
364
|
+
- [ ] Yarn Berry **PnP** — partially verified (scratch workspace): Tailwind leaf resolution is PnP-aware but points into the zip cache, so the node_modules symlink bridge is skipped by design (see "Tailwind CSS rules"); root-declared `tailwindcss` verified working; full config run (plugin loading, capability probes) still unverified
|
|
365
|
+
- [ ] Yarn 1 (classic) — workspace-root detection verified in a scratch workspace (no root env, `npm prefix`/lockfile-walk path); full config unverified
|
|
366
|
+
- [ ] pnpm — workspace-root detection verified in a scratch workspace (`pnpm root -w`, no usable env); full config unverified
|
|
367
|
+
- [ ] npm — root probes verified (`npm_config_local_prefix`, workspace-aware `npm prefix`); full config unverified
|
|
217
368
|
- ESLint 9
|
|
218
369
|
- [x] https://github.com/microsoft/rushstack/issues/4635 Failed to patch ESLint because the calling module was not recognized
|
|
219
370
|
- [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/nx.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import jsoncParser from 'jsonc-eslint-parser';
|
|
4
|
+
|
|
5
|
+
import { hasNx, toolGate } from '../lib.js';
|
|
6
|
+
|
|
7
|
+
// lazy so consumers without Nx don't pay the load cost (it drags in a large part of nx itself) -
|
|
8
|
+
// re-exported from index.js
|
|
9
|
+
export const nxPlugin = hasNx ? (await import('@nx/eslint-plugin')).default : null;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Nx blocks: plugin registration + `@nx/dependency-checks` on every `package.json`.
|
|
13
|
+
*
|
|
14
|
+
* Only `flat/base` (registers the '@nx' plugin, no rules of its own).
|
|
15
|
+
*
|
|
16
|
+
* `flat/typescript`/`flat/javascript` were deliberately NOT used - same call as with eslint-plugin-unicorn's
|
|
17
|
+
* recommended: they bundle the ENTIRE @stylistic plugin (hundreds of formatting rules - indent, quotes,
|
|
18
|
+
* semi, comma-dangle, ...) which would directly fight Prettier, plus a second full copy of
|
|
19
|
+
* @typescript-eslint/recommended that would relitigate rules already configured deliberately here.
|
|
20
|
+
*
|
|
21
|
+
* @param {boolean | import('../index.js').ToggleOptions} [option] the defineLintConfig `nx` flag; auto-detected (workspace `nx.json`) when omitted
|
|
22
|
+
* @param {boolean} [strict] same-scope detection only: `nx.json` at cwd instead of the workspace root (defineLintConfig `detection.strict`)
|
|
23
|
+
* @returns {Promise<import('eslint').Linter.Config[]>}
|
|
24
|
+
*/
|
|
25
|
+
export async function nxConfig(option, strict = false) {
|
|
26
|
+
const { enabled } = toolGate(option, strict, {
|
|
27
|
+
tool: 'nx',
|
|
28
|
+
has: hasNx,
|
|
29
|
+
// hasNx is the one non-strict `has*` (a workspace-root file check) - strict stays at cwd
|
|
30
|
+
strictHas: strict && existsSync(resolve(process.cwd(), 'nx.json')),
|
|
31
|
+
});
|
|
32
|
+
if (!enabled) return [];
|
|
33
|
+
const nx = (await import('@nx/eslint-plugin')).default;
|
|
34
|
+
return [
|
|
35
|
+
...nx.configs['flat/base'],
|
|
36
|
+
{
|
|
37
|
+
name: '@nx/dependency-checks',
|
|
38
|
+
files: ['**/package.json'],
|
|
39
|
+
languageOptions: {
|
|
40
|
+
parser: jsoncParser,
|
|
41
|
+
},
|
|
42
|
+
rules: {
|
|
43
|
+
// https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/dependency-checks
|
|
44
|
+
'@nx/dependency-checks': 'error',
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
];
|
|
48
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import prettierFlat from 'eslint-config-prettier/flat';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Prettier compatibility: turns off all rules that would fight the formatter.
|
|
5
|
+
*
|
|
6
|
+
* @see https://github.com/prettier/eslint-plugin-prettier?tab=readme-ov-file#arrow-body-style-and-prefer-arrow-callback-issue
|
|
7
|
+
* Plugin is not recommended by Prettier, they suggest to just use config, and disable all the rules, except for
|
|
8
|
+
* these two in plugin last since they disable some previously set rules:
|
|
9
|
+
* import prettierConfigRecommended from 'eslint-plugin-prettier/recommended';
|
|
10
|
+
* 'arrow-body-style': 'off'
|
|
11
|
+
* 'prefer-arrow-callback': 'off',
|
|
12
|
+
*
|
|
13
|
+
* @see https://nextjs.org/docs/app/api-reference/config/eslint#with-prettier
|
|
14
|
+
* Note the `/flat` suffix here, the difference from default entry is that `/flat` added `name` property to the
|
|
15
|
+
* exported object to improve https://eslint.org/blog/2024/04/eslint-config-inspector/ experience.
|
|
16
|
+
*
|
|
17
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
18
|
+
*/
|
|
19
|
+
export function prettierConfig() {
|
|
20
|
+
return [prettierFlat];
|
|
21
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import promisePlugin from 'eslint-plugin-promise';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Promise rules: recommended + overrides.
|
|
5
|
+
*
|
|
6
|
+
* @returns {import('eslint').Linter.Config[]}
|
|
7
|
+
*/
|
|
8
|
+
export function promiseConfig() {
|
|
9
|
+
return [
|
|
10
|
+
promisePlugin.configs['flat/recommended'],
|
|
11
|
+
{
|
|
12
|
+
name: 'eslint-plugin-promise overrides',
|
|
13
|
+
rules: {
|
|
14
|
+
'promise/prefer-await-to-then': 'warn',
|
|
15
|
+
'promise/param-names': 'off',
|
|
16
|
+
'promise/always-return': 'off',
|
|
17
|
+
'promise/catch-or-return': 'off',
|
|
18
|
+
},
|
|
19
|
+
},
|
|
20
|
+
];
|
|
21
|
+
}
|