@kirill.konshin/lint 0.2.0 → 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/index.js CHANGED
@@ -1,624 +1,126 @@
1
1
  /*
2
2
  * Raw ESM JS on purpose (no TS build): loaded by `eslint.config.mjs` and pre-commit `lint:staged`
3
3
  * before anything is built, so a `dist/` main would need building before it could lint. See
4
- * README ("Why raw JS").
4
+ * README ("Why raw JS"). Types live in the hand-written `index.d.ts` next to this file, which
5
+ * pulls real types from the underlying packages; the option types (LintOptions, NextOptions,
6
+ * TailwindOptions) are defined ONLY there and referenced from JSDoc via import() aliases - keep
7
+ * the function signatures in sync with the JSDoc here.
5
8
  *
6
- * jest/vitest plugins stay statically imported even though their recommended sets are gated below:
7
- * the runner-agnostic 'Test rules' block registers both plugins unconditionally (its rules are pure
8
- * AST checks that work without the runner installed).
9
- *
10
- * Plugins used only behind capability gates (and for the re-exports at the bottom) are imported
11
- * lazily so consumers without the tool don't pay their load cost — @nx/eslint-plugin in particular
12
- * drags in a large part of nx itself. Like storybookConfig below, the re-exported bindings are null
13
- * when the underlying tool isn't installed.
14
- *
15
- * Gate each test-runner's recommended rule set on the runner actually being installed - per
16
- * packages/lint/rules/testing.md ("if project use vite use vitest, otherwise jest"), a project
17
- * normally has exactly one of these, and applying the other runner's correctness rules to it would
18
- * be conceptually wrong (even if mechanically harmless, since the rule namespaces don't collide).
19
- */
20
- import { dirname, resolve } from 'node:path';
21
- import { fileURLToPath } from 'node:url';
22
- import { includeIgnoreFile as includeIgnoreFileCompat } from '@eslint/compat';
23
- import js from '@eslint/js';
24
- import vitestPlugin from '@vitest/eslint-plugin';
25
- import nextTs from 'eslint-config-next/typescript';
26
- import prettierFlat from 'eslint-config-prettier/flat';
27
- import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript';
28
- import importXPlugin, { createNodeResolver } from 'eslint-plugin-import-x';
29
- import jestPlugin from 'eslint-plugin-jest';
30
- import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
31
- import promisePlugin from 'eslint-plugin-promise';
32
- import reactPlugin from 'eslint-plugin-react';
33
- import reactHooksPlugin from 'eslint-plugin-react-hooks';
34
- import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
35
- import unicornPlugin from 'eslint-plugin-unicorn';
36
- import unusedImportsPlugin from 'eslint-plugin-unused-imports';
37
- import globals from 'globals';
38
- import jsoncParser from 'jsonc-eslint-parser';
39
-
40
- import { findTailwindEntry } from './findTailwindEntry.js';
41
- import { GLOBAL_IGNORES, hasWorkspaceFile, isPackageResolvable } from './lib.js';
42
- import { testColocation } from './ruleTestColocation.js';
43
-
44
- export const tsExtsRaw = 'js,jsx,ts,tsx,cjs,cts,mjs,mts'; // TODO mdx, needs loader
45
- export const eslintExtsRaw = `${tsExtsRaw},md,mdx,htm,html,vue`;
46
- export const prettierExtsRaw = 'css,scss,sass,less,yml,yaml,json,json5,jsonc,graphql,graphqls,xml';
47
-
48
- export const tsExts = `{${tsExtsRaw}}`;
49
- export const eslintExts = `*.{${eslintExtsRaw}}`;
50
- export const prettierExts = `*.{${prettierExtsRaw}}`;
51
-
52
- export const hasNext = isPackageResolvable('next/package.json');
53
- export const hasStorybook = isPackageResolvable('storybook/package.json');
54
- export const hasVite = isPackageResolvable('vite/package.json');
55
- export const hasJest = isPackageResolvable('jest/package.json');
56
- export const hasVitest = isPackageResolvable('vitest/package.json');
57
- export const hasTurbo = isPackageResolvable('turbo/package.json');
58
- export const hasNx = hasWorkspaceFile('nx.json');
59
- export const hasTailwind = isPackageResolvable('tailwindcss/package.json');
60
-
61
- const nextPlugin = hasNext ? (await import('@next/eslint-plugin-next')).default : null;
62
-
63
- export const tailwindEntry = hasTailwind ? findTailwindEntry(GLOBAL_IGNORES) : null;
64
-
65
- const ENABLE_TYPE_AWARE_RULES = false;
66
-
67
- /*
68
- * `eslint-plugin-storybook` is a dependency of this package (like `@next/eslint-plugin-next` is for
69
- * Next), but its own code statically imports the `storybook` package itself, which most consumers won't
70
- * have installed - it's an optional peer here, same as `next` the framework is for `@next/eslint-plugin-next`.
71
- * Resolve it lazily so loading this module doesn't crash for non-Storybook consumers; `storybookConfig`
72
- * is exported as `null` if it couldn't be resolved, mirroring how `nextPlugin` is always importable but
73
- * only useful where the underlying tool is actually installed.
74
- */
75
- let storybookConfig = null;
76
- try {
77
- //TODO Add hasStorybook?
78
- const storybook = await import('eslint-plugin-storybook');
79
- storybookConfig = storybook.default.configs['flat/recommended'];
80
- } catch {
81
- // `storybook` isn't installed in this project - `storybookConfig` stays null.
82
- }
83
-
84
- /*
85
- * `eslint-config-next`'s own parser module does `require('next/dist/compiled/babel/eslint-parser')` -
86
- * a file INSIDE the `next` package itself - so merely *importing* `eslint-config-next` crashes if
87
- * `next` isn't installed at all, regardless of any later conditional logic (verified empirically: it
88
- * throws "Cannot find module 'next/dist/compiled/babel/eslint-parser'" the instant the module loads).
89
- * Mirror the eslint-plugin-storybook pattern above: only import it when `next` is actually there.
90
- */
91
- let nextConfig = [];
92
- if (hasNext) {
93
- try {
94
- const next = await import('eslint-config-next');
95
- nextConfig = next.default;
96
- } catch {
97
- // shouldn't happen given hasNext already confirmed `next/package.json` resolves, but stay safe
98
- }
99
- }
100
-
101
- /*
102
- * Non-Next React projects - this config is also used for Vite+React apps - still want React/React
103
- * Hooks/jsx-a11y linting, which `eslint-config-next` normally provides but only via the Next-specific
104
- * parser above. Cover the same ground directly instead, with whatever parser is already active
105
- * (typescript-eslint for .ts/.tsx via `nextTs` below, the default parser otherwise).
9
+ * The config is built by `defineLintConfig(options)`, which is pure ordering: every block lives in a
10
+ * themed `configs/*.js` file as an exported `*Config()` function, and the tool-gated ones take
11
+ * their own defineLintConfig flag (`undefined` auto-detect / `true` or options force on / `false` off)
12
+ * and gate themselves - see the detection block in lib.js for why forcing exists. Tool-gated
13
+ * plugins are imported
14
+ * lazily inside their block functions so consumers without the tool don't pay their load cost;
15
+ * the plugin re-exports below follow module-load DETECTION (not defineLintConfig options, which they
16
+ * cannot see) and are null when the tool wasn't detected.
106
17
  */
107
- const reactFallbackConfig = hasNext
108
- ? []
109
- : [
110
- reactPlugin.configs.flat.recommended,
111
- reactPlugin.configs.flat['jsx-runtime'],
112
- reactHooksPlugin.configs.flat['recommended-latest'],
113
- jsxA11yPlugin.flatConfigs.recommended,
114
- ];
115
-
116
- // lazy for the same reason as nextPlugin above
117
- const turboPlugin = hasTurbo ? (await import('eslint-plugin-turbo')).default : null;
118
- const nxPlugin = hasNx ? (await import('@nx/eslint-plugin')).default : null;
119
- const tailwindPlugin = hasTailwind ? (await import('eslint-plugin-tailwindcss')).default : null;
120
-
121
- const index = [
122
- js.configs.recommended,
123
-
124
- /*
125
- * `eslint-config-next` already ignores `next-env.d.ts`, but only as a bare pattern ('next-env.d.ts'),
126
- * which only matches at the config's own root - not when the Next app (and its generated
127
- * next-env.d.ts) lives in a subdirectory, like demo/web-static/ here. It's auto-generated and
128
- * explicitly marked "should not be edited", so exclude it recursively instead of just working
129
- * around individual rules (its `///` reference directives otherwise trip multiline-comment-style,
130
- * which would corrupt them if autofixed into a `/* *\/` block).
131
- */
132
- {
133
- ignores: GLOBAL_IGNORES,
134
- },
135
-
136
- ...nextConfig,
137
- ...nextTs,
138
- ...reactFallbackConfig,
139
-
140
- /*
141
- * @see https://github.com/prettier/eslint-plugin-prettier?tab=readme-ov-file#arrow-body-style-and-prefer-arrow-callback-issue
142
- * Plugin is not recommended by Prettier, they suggest to just use config, and disable all the rules, except for
143
- * these two in plugin last since they disable some previously set rules:
144
- * import prettierConfigRecommended from 'eslint-plugin-prettier/recommended';
145
- * 'arrow-body-style': 'off'
146
- * 'prefer-arrow-callback': 'off',
147
- *
148
- * @see https://nextjs.org/docs/app/api-reference/config/eslint#with-prettier
149
- * Note the `/flat` suffix here, the difference from default entry is that `/flat` added `name` property to the
150
- * exported object to improve https://eslint.org/blog/2024/04/eslint-config-inspector/ experience.
151
- */
152
- prettierFlat,
153
-
154
- ...(storybookConfig ?? []),
155
-
156
- /*
157
- * eslint-config-next already registers `eslint-plugin-import` under the 'import' key, and ESLint 10
158
- * hard-errors ("Cannot redefine plugin") if a later config tries to reuse that same key with a
159
- * different plugin instance. eslint-plugin-import-x is a drop-in replacement, registered under its
160
- * own 'import-x' key instead (its own recommended config does this registration for us).
161
- */
162
- importXPlugin.configs['flat/recommended'],
163
-
164
- promisePlugin.configs['flat/recommended'],
165
-
166
- {
167
- name: 'eslint-plugin-import-x overrides',
168
- settings: {
169
- /*
170
- * `createTypeScriptImportResolver` correctly resolves relative imports and simple TS path
171
- * aliases, but NOT cross-workspace-package imports in this monorepo (e.g. `@kirill.konshin/node`)
172
- * or subpath exports (e.g. `next/constants`) - verified empirically. That's why the
173
- * resolution-dependent rules below are turned off rather than left on the recommended default.
174
- */
175
- 'import-x/resolver-next': [createTypeScriptImportResolver(), createNodeResolver()],
176
- },
177
- rules: {
178
- /*
179
- * Off because of the workspace/subpath resolution gaps above - re-enable per-project once
180
- * resolution is confirmed reliable there (e.g. a single-app, non-monorepo consumer).
181
- */
182
- 'import-x/no-unresolved': 'off',
183
- 'import-x/named': 'off',
184
- 'import-x/namespace': 'off',
185
- 'import-x/default': 'off',
186
- 'import-x/export': 'off',
187
- /*
188
- * Same resolution caveat, and also the two most expensive rules in the recommended set
189
- * (they parse every imported module looking for its named exports).
190
- */
191
- 'import-x/no-named-as-default': 'off',
192
- 'import-x/no-named-as-default-member': 'off',
193
- 'import-x/no-default-export': 'warn', // see 'Storybook overrides' below
194
- },
195
- },
196
-
197
- {
198
- name: 'eslint-plugin-simple-import-sort',
199
- files: [`**/*.${tsExts}`],
200
- plugins: { 'simple-import-sort': simpleImportSortPlugin },
201
- rules: {
202
- /*
203
- * Side-effect imports (polyfills, CSS) ARE sorted into their group; the sorter only
204
- * preserves the relative order of multiple side-effect imports that land in the SAME
205
- * group (so order-dependent side effects stay put). Non-import code between imports
206
- * splits them into independently-sorted chunks (standard simple-import-sort behavior).
207
- */
208
- 'simple-import-sort/imports': [
209
- 'error',
210
- {
211
- groups: [
212
- // 1. Polyfills - side-effect imports that must run first
213
- ['^\\u0000.*(polyfill|core-js|regenerator-runtime|whatwg-fetch|@vitest/web-worker)'],
214
- // 2. React
215
- ['^react(-dom)?(/|$)'],
216
- // 3. Third-party packages (node: builtins + npm packages)
217
- ['^node:', '^@?\\w'],
218
- // 4. Local imports - path aliases then relative
219
- ['^@/', '^\\.'],
220
- // 5. CSS/styles from libraries (side-effect, package path)
221
- ['^\\u0000@?\\w'],
222
- // 6. Local CSS/styles (side-effect, relative path)
223
- ['^\\u0000'],
224
- ],
225
- },
226
- ],
227
- },
228
- },
229
-
230
- {
231
- name: 'Globals',
232
- languageOptions: {
233
- globals: {
234
- ...globals.browser,
235
- ...globals.node,
236
- },
237
- },
238
- },
239
-
240
- {
241
- name: 'ESLint overrides',
242
- rules: {
243
- 'no-restricted-imports': [
244
- 'error',
245
- {
246
- paths: [
247
- {
248
- name: 'next/router',
249
- message: 'Please use next/navigation instead of next/router',
250
- },
251
- ],
252
- },
253
- ],
254
- // 'multiline-comment-style': ['warn', 'starred-block'],
255
- 'multiline-comment-style': 'off',
256
- },
257
- },
258
-
259
- {
260
- name: 'eslint-config-next overrides',
261
- rules: {
262
- '@next/next/no-html-link-for-pages': 'off',
263
- '@next/next/no-img-element': 'off',
264
- 'import/no-anonymous-default-export': 'off', // overrides eslint-config-next's own default
265
- 'jsx-a11y/alt-text': 'off',
266
- 'react/prop-types': 'off', // ts does it statically
267
- },
268
- },
269
-
270
- {
271
- name: '@typescript-eslint overrides',
272
- files: [`**/*.${tsExts}`],
273
- rules: {
274
- '@typescript-eslint/explicit-module-boundary-types': 'off',
275
- '@typescript-eslint/no-empty-function': 'off',
276
- '@typescript-eslint/no-explicit-any': 'off',
277
- '@typescript-eslint/no-require-imports': 'off',
278
- '@typescript-eslint/no-unused-vars': 'off', // superseded by 'unused-imports/no-unused-imports' below, which is actually autofixable
279
- '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
280
- '@typescript-eslint/consistent-type-imports': [
281
- 'error',
282
- { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
283
- ],
284
- '@typescript-eslint/ban-ts-comment': [
285
- 'error',
286
- {
287
- 'ts-expect-error': 'allow-with-description',
288
- 'ts-ignore': true,
289
- 'ts-nocheck': true,
290
- 'ts-check': false,
291
- minimumDescriptionLength: 3,
292
- },
293
- ],
294
- /*
295
- * `as const` is the mechanical half of "Prefer `as const` and `readonly` for immutable
296
- * constants and objects" - the `readonly` half is a per-case judgment call (which objects
297
- * deserve it), so that guidance stays in typescript.md instead of being lint-enforced here.
298
- */
299
- '@typescript-eslint/prefer-as-const': 'error',
300
- },
301
- },
302
-
303
- {
304
- name: 'eslint-plugin-unused-imports',
305
- plugins: { 'unused-imports': unusedImportsPlugin },
306
- rules: {
307
- /*
308
- * Unlike `@typescript-eslint/no-unused-vars/core` `no-unused-vars`, this rule is
309
- * autofixable - `--fix` deletes the unused import specifier (or the whole import
310
- * statement if nothing from it is used) instead of just reporting it.
311
- */
312
- 'unused-imports/no-unused-imports': 'error',
313
- },
314
- },
315
-
316
- {
317
- name: 'Unicorn rules',
318
- /*
319
- * Deliberately NOT using unicorn.configs['flat/recommended'] - it's 337 rules (it even folds in
320
- * a few unprefixed core-ESLint rules), extremely opinionated, and far beyond what was asked for.
321
- * Only the two rules below are actually wanted.
322
- */
323
- files: [`**/*.${tsExts}`],
324
- plugins: { unicorn: unicornPlugin },
325
- rules: {
326
- 'unicorn/filename-case': [
327
- 'error',
328
- {
329
- case: 'camelCase',
330
- /*
331
- * code-style.md only mandates FILE names; this repo's own kebab-case package
332
- * directories (e.g. electron-builder, react-native) are an established convention.
333
- */
334
- checkDirectories: false,
335
- // Next.js App Router mandates these exact hyphenated filenames - not a naming choice.
336
- ignore: [
337
- /^not-found\.[jt]sx?$/,
338
- /^global-error\.[jt]sx?$/,
339
- /^opengraph-image\.[jt]sx?$/,
340
- /^twitter-image\.[jt]sx?$/,
341
- /^apple-icon\.[jt]sx?$/,
342
- /^mdx-components\.[jt]sx?$/,
343
- /\.d\.tsx?$/,
344
- /^electron-builder\..+$/,
345
- ],
346
- },
347
- ],
348
- 'unicorn/prefer-node-protocol': 'error',
349
- },
350
- },
351
-
352
- {
353
- name: 'eslint-plugin-promise overrides',
354
- rules: {
355
- 'promise/prefer-await-to-then': 'warn',
356
- 'promise/param-names': 'off',
357
- 'promise/always-return': 'off',
358
- 'promise/catch-or-return': 'off',
359
- },
360
- },
361
-
362
- //FIXME Does not perform, turned off
363
- ENABLE_TYPE_AWARE_RULES
364
- ? {
365
- name: 'Type-aware rules (separate for performance)',
366
- files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts', '**/*.mdx'],
367
- languageOptions: {
368
- parserOptions: {
369
- projectService: {
370
- /*
371
- * Config files like vite.config.ts and .storybook/{main,preview}.ts sit at the
372
- * package root or in a dotfolder, outside its own tsconfig.json `include: ["src"]`
373
- * - projectService has no tsconfig to attach them to otherwise. allowDefaultProject
374
- * falls back to a synthetic single-file program for these instead of erroring.
375
- * `**` isn't allowed here, so root-level, one-level-nested, and this monorepo's own
376
- * packages/* layout are each spelled out explicitly.
377
- */
378
- allowDefaultProject: [
379
- //FIXME NOT PROJECT AGNOSTIC
380
- 'vite.config.ts',
381
- '*/vite.config.ts',
382
- 'packages/*/vite.config.ts',
383
- '.storybook/main.ts',
384
- '*/.storybook/main.ts',
385
- 'packages/*/.storybook/main.ts',
386
- '.storybook/preview.ts',
387
- '*/.storybook/preview.ts',
388
- 'packages/*/.storybook/preview.ts',
389
- ],
390
- // Default cap is 8; this monorepo alone has 14 vite.config.ts + 10 .storybook/*.ts files.
391
- maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50,
392
- },
393
- tsconfigRootDir: process.cwd(),
394
- },
395
- },
396
- rules: {
397
- '@typescript-eslint/prefer-optional-chain': 'warn',
398
- '@typescript-eslint/prefer-nullish-coalescing': 'warn',
399
-
400
- /**
401
- * https://typescript-eslint.io/rules/naming-convention/
402
- *
403
- * Naming Conventions. Lives here (not 'Custom
404
- * rules') because the `types: ['boolean']` filter below needs type info too, even
405
- * though naming-convention as a whole isn't in the typed-linting rule set.
406
- */
407
- '@typescript-eslint/naming-convention': [
408
- 'warn',
409
- { selector: 'default', format: null },
410
- /*
411
- * PascalCase allowed too: this codebase's actual
412
- * convention is `const Cmp: FC<Props> = memo(...)` - components are PascalCase
413
- * variables, not just PascalCase function declarations.
414
- */
415
- {
416
- selector: 'variable',
417
- format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
418
- leadingUnderscore: 'forbid',
419
- },
420
- {
421
- selector: 'variable',
422
- types: ['boolean'],
423
- /*
424
- * The part AFTER the prefix is naturally capitalized (isLoading, hasError, ...),
425
- * so it's validated as PascalCase, not camelCase - format here is for the suffix,
426
- * not the identifier as a whole.
427
- */
428
- format: ['PascalCase'],
429
- prefix: ['is', 'has', 'had', 'can', 'should', 'will', 'did'],
430
- },
431
- /*
432
- * Established exceptions to the boolean-prefix rule above - conventional enough on
433
- * their own (React's own `loading`/`done` state names, DOM/library `enabled` flags)
434
- * that requiring is/has/can/should here would just be noise.
435
- */
436
- {
437
- selector: 'variable',
438
- types: ['boolean'],
439
- filter: { regex: '^(done|loading|enabled)$', match: true },
440
- format: ['camelCase'],
441
- },
442
- { selector: 'function', format: ['camelCase', 'PascalCase'] },
443
- { selector: 'class', format: ['PascalCase'] },
444
- ],
445
- },
446
- }
447
- : null,
448
-
449
- {
450
- name: 'Default export overrides',
451
- files: [
452
- '**/*.config.*',
453
- `**/*.stories.${tsExts}`,
454
- `**/.storybook/main.${tsExts}`,
455
- `**/.storybook/preview.${tsExts}`,
456
- '**/.lintstagedrc*',
457
- '**/.prettierrc*',
458
- `**/App.${tsExts}`,
459
- `**/index.${tsExts}`,
460
- `**/main.${tsExts}`,
461
- '**/*.d.ts',
462
- `**/default.${tsExts}`,
463
- `**/error.${tsExts}`,
464
- `**/forbidden.${tsExts}`,
465
- `**/global-error.${tsExts}`,
466
- `**/layout.${tsExts}`,
467
- `**/loading.${tsExts}`,
468
- `**/not-found.${tsExts}`,
469
- `**/page.${tsExts}`,
470
- `**/template.${tsExts}`,
471
- `**/unauthorized.${tsExts}`,
472
- `**/apple-icon.${tsExts}`,
473
- `**/icon.${tsExts}`,
474
- `**/manifest.${tsExts}`,
475
- `**/opengraph-image.${tsExts}`,
476
- `**/robots.${tsExts}`,
477
- `**/sitemap.${tsExts}`,
478
- `**/twitter-image.${tsExts}`,
479
- ],
480
- rules: {
481
- /*
482
- * Stories always default-export `meta`, and story exports (`Default`, `WithArgs`, ...) are PascalCase by
483
- * Storybook's own convention, which the general rules above disallow.
484
- */
485
- 'import-x/no-default-export': 'off',
486
- '@typescript-eslint/naming-convention': 'off',
487
- },
488
- },
489
-
490
- ...(hasTurbo
491
- ? [
492
- turboPlugin.configs['flat/recommended'],
493
- {
494
- name: 'eslint-plugin-turbo overrides',
495
- rules: {
496
- /*
497
- * Only covers undeclared env vars, not the full dependsOn/outputs consistency - that part has no
498
- * ESLint-shaped check. Downgraded from their default 'error' to 'warn'.
499
- */
500
- 'turbo/no-undeclared-env-vars': 'warn',
501
- },
502
- },
503
- ]
504
- : []),
505
-
506
- /*
507
- * Recommended rules (warnings + `no-contradicting-classname` as error), re-scoped from the
508
- * plugin's global js/jsx/ts/tsx default to only the detected Tailwind project dirs - see the
509
- * two-gate comment above findTailwindProjectDirs().
510
- */
511
- /*
512
- * Standalone block (simple to override wholesale), auto-added only when exactly one Tailwind v4
513
- * entry CSS was found - see the auto-find comment above findTailwindEntry(). Recommended rules:
514
- * warnings + `no-contradicting-classname` as error.
515
- */
516
- ...(tailwindEntry
517
- ? [
518
- {
519
- ...tailwindPlugin.configs.recommended,
520
- settings: { tailwindcss: { cssConfigPath: tailwindEntry } },
521
- },
522
- ]
523
- : []),
524
-
525
- ...(hasNx
526
- ? [
527
- /*
528
- * Only `flat/base` (registers the '@nx' plugin, no rules of its own).
529
- *
530
- * `flat/typescript`/ `flat/javascript` were deliberately NOT used - same call as with eslint-plugin-unicorn's
531
- * recommended: they bundle the ENTIRE @stylistic plugin (hundreds of formatting rules - indent, quotes,
532
- * semi, comma-dangle, ...) which would directly fight Prettier, plus a second full copy of
533
- * @typescript-eslint/recommended that would relitigate rules already configured deliberately above.
534
- */
535
- ...nxPlugin.configs['flat/base'],
536
- {
537
- name: '@nx/dependency-checks',
538
- files: ['**/package.json'],
539
- languageOptions: {
540
- parser: jsoncParser,
541
- },
542
- rules: {
543
- // https://nx.dev/docs/technologies/eslint/eslint-plugin/guides/dependency-checks
544
- '@nx/dependency-checks': 'error',
545
- },
546
- },
547
- ]
548
- : []),
549
-
550
- ...(hasJest
551
- ? [
552
- {
553
- ...jestPlugin.configs['flat/recommended'],
554
- name: 'Jest Rules',
555
- files: [`**/*.{test,spec}.${tsExts}`],
556
- },
557
- ]
558
- : []),
559
-
560
- ...(hasVitest
561
- ? [
562
- {
563
- ...vitestPlugin.configs.recommended,
564
- name: 'Vitest Rules',
565
- files: [`**/*.{test,spec}.${tsExts}`],
566
- },
567
- {
568
- ...vitestPlugin.configs.env,
569
- name: 'Vitest globals',
570
- files: [`**/*.{test,spec}.${tsExts}`],
571
- },
572
- ]
573
- : []),
574
-
575
- {
576
- /*
577
- * Runner-agnostic: this rule is pure AST/call-name checking, needs neither jest nor vitest
578
- * installed to work correctly, so it applies regardless of which one (if either) is present.
579
- */
580
- name: 'Test rules',
581
- files: [`**/*.{test,spec}.${tsExts}`],
582
- plugins: {
583
- jest: jestPlugin,
584
- vitest: vitestPlugin,
585
- local: { rules: { 'test-colocation': testColocation } },
586
- },
587
- rules: {
588
- 'jest/consistent-test-it': ['error', { fn: 'test' }],
589
- 'vitest/consistent-test-it': ['error', { fn: 'test' }],
590
- 'local/test-colocation': 'error',
591
- 'jest/no-disabled-tests': 'warn',
592
- 'vitest/no-disabled-tests': 'warn',
593
- },
594
- },
595
-
596
- /*
597
- * FIXME ESLint 10 + Next fix
598
- * https://github.com/vercel/next.js/issues/89764
599
- * https://gist.github.com/OscarGauss/1f305edf5b7c103bb2ee32ba479f4261
600
- */
601
- {
602
- settings: {
603
- react: { version: '19' },
604
- },
605
- },
606
- ].filter(Boolean);
607
-
608
- export default index;
609
-
610
- export { nextPlugin, nxPlugin, turboPlugin, jestPlugin, vitestPlugin, findTailwindEntry };
18
+ import { baseConfig, defaultIgnoreConfig } from './configs/base.js';
19
+ import { importSortConfig, importXConfig, unusedImportsConfig } from './configs/imports.js';
20
+ import { nextConfig, nextOverridesConfig, reactSettingsConfig, typescriptOverridesConfig } from './configs/next.js';
21
+ import { nxConfig } from './configs/nx.js';
22
+ import { prettierConfig } from './configs/prettier.js';
23
+ import { promiseConfig } from './configs/promise.js';
24
+ import { storybookConfig } from './configs/storybook.js';
25
+ import { tailwindConfig } from './configs/tailwind.js';
26
+ import { jestConfig, testConfig, vitestConfig } from './configs/testing.js';
27
+ import { turboConfig } from './configs/turbo.js';
28
+ import { typeAwareConfig } from './configs/typescriptTypeAware.js';
29
+ import { unicornConfig } from './configs/unicorn.js';
30
+ import { eslintExts, prettierExts } from './lib.js';
31
+
32
+ export * from './configs/base.js';
33
+ export * from './configs/imports.js';
34
+ export * from './configs/next.js';
35
+ export * from './configs/nx.js';
36
+ export * from './configs/prettier.js';
37
+ export * from './configs/promise.js';
38
+ export * from './configs/storybook.js';
39
+ export * from './configs/tailwind.js';
40
+ export * from './configs/testing.js';
41
+ export * from './configs/turbo.js';
42
+ export * from './configs/typescriptTypeAware.js';
43
+ export * from './configs/unicorn.js';
44
+
45
+ // deliberately NOT the whole lib.js - asOptions/GLOBAL_IGNORES and the fs helpers stay internal
46
+ export {
47
+ // extensions
48
+ tsExts,
49
+ tsExtsRaw,
50
+ eslintExts,
51
+ eslintExtsRaw,
52
+ prettierExts,
53
+ prettierExtsRaw,
54
+ // detection
55
+ findWorkspaceRoot,
56
+ scanWorkspace,
57
+ hasJest,
58
+ hasNext,
59
+ hasNx,
60
+ hasStorybook,
61
+ hasTailwind,
62
+ hasTurbo,
63
+ hasVite,
64
+ hasVitest,
65
+ } from './lib.js';
66
+
67
+ /** @typedef {import('./index.js').LintOptions} LintOptions Per-tool toggles - defined once in index.d.ts (resolved via the sibling declaration file), backed by real upstream types. */
611
68
 
612
69
  /**
613
- * @param {string} importMetaUrl
614
- * @param {string} ignoreFile
615
- * @returns {import('@eslint/core').ConfigObject}
70
+ * Build the shared flat ESLint config.
71
+ *
72
+ * By default every tool integration is auto-detected (see the `has*` exports); pass
73
+ * {@link LintOptions} to force any of them on/off or to supply tool-specific settings.
74
+ *
75
+ * Returns a Promise - ESLint natively awaits a Promise default export, so a plain
76
+ * `export default defineLintConfig({...})` works; `await` it only when composing with extra blocks.
77
+ *
78
+ * @param {LintOptions | Promise<LintOptions> | (() => LintOptions | Promise<LintOptions>)} [options]
79
+ * @returns {Promise<import('eslint').Linter.Config[]>}
616
80
  */
617
- export function includeIgnoreFile(importMetaUrl, ignoreFile) {
618
- // @see https://blog.linotte.dev/eslint-9-next-js-935c2b6d0371
619
- return includeIgnoreFileCompat(resolve(dirname(fileURLToPath(importMetaUrl)), ignoreFile));
81
+ export async function defineLintConfig(options = {}) {
82
+ if (typeof options === 'function') options = options();
83
+ options = (await options) ?? {};
84
+
85
+ // blocks from the same configs/* file stay consecutive - ordering inside a family matters
86
+ // (e.g. next: base config, then the TS wiring stemming from it, then overrides, then settings)
87
+ return [
88
+ // base.js
89
+ ...baseConfig(),
90
+ ...defaultIgnoreConfig(options.defaultIgnore),
91
+ // next.js
92
+ ...(await nextConfig(options.next)),
93
+ ...typescriptOverridesConfig(),
94
+ ...nextOverridesConfig(),
95
+ ...reactSettingsConfig(),
96
+ // prettier.js
97
+ ...prettierConfig(),
98
+ // storybook.js
99
+ ...(await storybookConfig(options.storybook)),
100
+ // typescriptTypeAware (should be before imports)
101
+ ...typeAwareConfig(options.typeAware),
102
+ // imports.js
103
+ ...importXConfig(),
104
+ ...importSortConfig(),
105
+ ...unusedImportsConfig(),
106
+ // promise.js
107
+ ...promiseConfig(),
108
+ // unicorn.js
109
+ ...unicornConfig(),
110
+ // turbo.js
111
+ ...(await turboConfig(options.turbo)),
112
+ // tailwind.js
113
+ ...(await tailwindConfig(options.tailwind)),
114
+ // nx.js
115
+ ...(await nxConfig(options.nx)),
116
+ // testing.js
117
+ ...jestConfig(options.jest),
118
+ ...vitestConfig(options.vitest),
119
+ ...testConfig(),
120
+ ];
620
121
  }
621
122
 
123
+ /** @type {import('prettier').Config} */
622
124
  export const prettier = {
623
125
  printWidth: 120,
624
126
  tabWidth: 2,
@@ -645,7 +147,7 @@ export const prettier = {
645
147
  *
646
148
  * TODO Screw yarn, just use eslint directly? Yarn gives greater control over what is in the console...
647
149
  *
648
- * @returns {import('lint-staged').Configuration}
150
+ * @type {import('lint-staged').Configuration}
649
151
  */
650
152
  export const listStaged = {
651
153
  [prettierExts]: ['yarn prettier'],