@kirill.konshin/lint 0.3.5 → 0.4.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.
Files changed (60) hide show
  1. package/README.md +135 -56
  2. package/dist/configs/base.d.ts +29 -0
  3. package/dist/configs/base.d.ts.map +1 -0
  4. package/{configs → dist/configs}/base.js +7 -25
  5. package/dist/configs/imports.d.ts +21 -0
  6. package/dist/configs/imports.d.ts.map +1 -0
  7. package/{configs → dist/configs}/imports.js +0 -10
  8. package/dist/configs/nx.d.ts +16 -0
  9. package/dist/configs/nx.d.ts.map +1 -0
  10. package/{configs → dist/configs}/nx.js +3 -8
  11. package/dist/configs/prettier.d.ts +17 -0
  12. package/dist/configs/prettier.d.ts.map +1 -0
  13. package/{configs → dist/configs}/prettier.js +0 -3
  14. package/dist/configs/promise.d.ts +6 -0
  15. package/dist/configs/promise.d.ts.map +1 -0
  16. package/{configs → dist/configs}/promise.js +0 -3
  17. package/dist/configs/react.d.ts +84 -0
  18. package/dist/configs/react.d.ts.map +1 -0
  19. package/{configs → dist/configs}/react.js +14 -41
  20. package/dist/configs/storybook.d.ts +14 -0
  21. package/dist/configs/storybook.d.ts.map +1 -0
  22. package/{configs → dist/configs}/storybook.js +3 -6
  23. package/dist/configs/tailwind.d.ts +29 -0
  24. package/dist/configs/tailwind.d.ts.map +1 -0
  25. package/{configs → dist/configs}/tailwind.js +9 -24
  26. package/dist/configs/testing.d.ts +22 -0
  27. package/dist/configs/testing.d.ts.map +1 -0
  28. package/{configs → dist/configs}/testing.js +11 -25
  29. package/dist/configs/turbo.d.ts +9 -0
  30. package/dist/configs/turbo.d.ts.map +1 -0
  31. package/{configs → dist/configs}/turbo.js +6 -6
  32. package/dist/configs/typescriptTypeAware.d.ts +20 -0
  33. package/dist/configs/typescriptTypeAware.d.ts.map +1 -0
  34. package/{configs → dist/configs}/typescriptTypeAware.js +10 -23
  35. package/dist/configs/unicorn.d.ts +10 -0
  36. package/dist/configs/unicorn.d.ts.map +1 -0
  37. package/{configs → dist/configs}/unicorn.js +0 -4
  38. package/dist/index.d.ts +80 -0
  39. package/dist/index.d.ts.map +1 -0
  40. package/{index.js → dist/index.js} +5 -54
  41. package/dist/lib.d.ts +116 -0
  42. package/dist/lib.d.ts.map +1 -0
  43. package/{lib.js → dist/lib.js} +69 -145
  44. package/dist/lintPrepare.d.ts +105 -0
  45. package/dist/lintPrepare.d.ts.map +1 -0
  46. package/{lintPrepare.js → dist/lintPrepare.js} +12 -67
  47. package/dist/yarn.cjs +117 -0
  48. package/dist/yarn.d.cts +8 -0
  49. package/dist/yarn.d.cts.map +1 -0
  50. package/package.json +42 -34
  51. package/rules/code-style.md +2 -0
  52. package/rules/github.md +17 -9
  53. package/rules/gitlab.md +68 -17
  54. package/rules/mui.md +1 -1
  55. package/rules/nextjs.md +1 -1
  56. package/rules/npm-yarn.md +51 -6
  57. package/rules/nx.md +6 -6
  58. package/rules/typescript.md +13 -7
  59. package/rules/webstorm.md +20 -0
  60. package/index.d.ts +0 -281
package/rules/gitlab.md CHANGED
@@ -11,25 +11,67 @@ paths:
11
11
  # Example
12
12
 
13
13
  ```yml
14
- build:
15
- image: node:24
16
- env:
17
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
18
- cache:
19
- key:
20
- files:
21
- - yarn.lock
14
+ image: node:lts
15
+
16
+ variables:
17
+ YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
18
+
19
+ cache:
20
+ - key:
21
+ files:
22
+ - yarn.lock # dependencies cached based on lockfile
23
+ paths:
24
+ - .yarn
25
+ - .pnp.js
26
+ - yarn.lock
27
+ - node_modules
28
+ - '**/node_modules'
29
+ - key: $CI_COMMIT_REF_NAME # build-related files cached per-branch
30
+ paths:
31
+ - '**/.turbo'
32
+ - '**/.nx'
33
+ - '**/.tscache'
34
+ - '**/.tsbuildinfo'
35
+ - '**/.next/cache'
36
+
37
+ stages:
38
+ - install
39
+ - test
40
+ - build
41
+
42
+ # separate so that cache can pre-populate if other steps would fail, it speeds things up
43
+ before_script:
44
+ - corepack enable
45
+ - yarn install --immutable
46
+ - yarn prepare # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this line skipped
47
+
48
+ install:
49
+ stage: install
50
+ script:
51
+ - echo Done
52
+
53
+ lint:
54
+ stage: test
55
+ script:
56
+ - yarn lint
57
+
58
+ test:
59
+ stage: test
60
+ image: mcr.microsoft.com/playwright:v1.50.0-noble # keep in sync with installed Playwright version
61
+ artifacts:
62
+ when: always
22
63
  paths:
23
- - .yarn/cache
24
- - yarn.lock
25
- - node_modules
26
- - '**/node_modules'
27
- - '**/.turbo'
28
- - '**/.tscache'
29
- - '**/.next/cache'
64
+ - test-results
65
+ - test-results-html
66
+ reports:
67
+ junit: test-results/junit.xml
68
+ script:
69
+ - yarn test:playwright # https://playwright.dev/docs/ci#running-headed xvfb-run yarn test:playwright
70
+
71
+ # Not needed for Vercel-hosted projects
72
+ build:
73
+ stage: build
30
74
  script:
31
- - yarn --immutable
32
- - yarn prepare # Add this if Yarn 2+ is used and package is NOT private
33
75
  - yarn build
34
76
  only:
35
77
  - master
@@ -37,3 +79,12 @@ build:
37
79
  paths:
38
80
  - web/build
39
81
  ```
82
+
83
+ Cache `.yarn` individually is possible but not needed:
84
+
85
+ ```yaml
86
+ - .yarn/cache
87
+ - .yarn/unplugged
88
+ - .yarn/build-state.yml
89
+ - .yarn/install-state.gz
90
+ ```
package/rules/mui.md CHANGED
@@ -19,4 +19,4 @@ paths:
19
19
  # Next.js
20
20
 
21
21
  - When MUI is used with Next.js ALWAYS add barrel-heavy packages to `experimental.optimizePackageImports`: `@mui/material`, `@mui/system`, `@mui/icons-material`, `@mui/lab`, `@mui/x-data-grid`, `@toolpad/core`, plus the other usual suspects (`@fortawesome/*`, `@gravity-ui/icons`, `@gravity-ui/uikit`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons`)
22
- - Prefer `defineNextConfig` from `@kirill.konshin/next` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see nextjs.md)
22
+ - Prefer `defineNextConfig` from `@kirill.konshin/next/config` which sets the exhaustive list — extra entries are ignored, missing ones cost dev startup and bundle size (see nextjs.md)
package/rules/nextjs.md CHANGED
@@ -13,7 +13,7 @@ _EVERY_ Next.js page, layout, route handler or component must adhere to policy u
13
13
  - Use `iron-session` for authentication via `@kirill.konshin/auth`, see auth.md
14
14
  - Server-only modules (auth/session, DB access, anything touching secrets) MUST start with `import 'server-only'` (the npm package, add as dependency) — ENFORCED BY AGENT: no ESLint rule checks this, add it when creating such modules and flag it when reviewing
15
15
  - `package.json` MUST ALWAYS have version of Next.js, NEVER `*`, otherwise Vercel will fall into legacy mode instead of serverless
16
- - ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next`: sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons` — extra entries are ignored, missing ones cost dev startup and bundle size, see mui.md)
16
+ - ALWAYS create `next.config.ts` with `defineNextConfig` from `@kirill.konshin/next/config` (the `/config` subpath, NEVER the barrel — Next transpiles `next.config.ts` to CJS and `require`s it outside any bundler): sets `cacheComponents`, `typedRoutes`, `experimental.typedEnv`, `reactStrictMode: false` and an exhaustive `experimental.optimizePackageImports` (`@mui/*`, `@toolpad/core`, `@fortawesome/*`, `@gravity-ui/*`, `lodash`, `@heroui/react`, `react-bootstrap`, `@kirill.konshin/icons` — extra entries are ignored, missing ones cost dev startup and bundle size, see mui.md)
17
17
  - Use `@kirill.konshin/icons` for FontAwesome / Gravity UI icons — the barrel is safe with `optimizePackageImports` (`defineNextConfig` sets it)
18
18
 
19
19
  # Admin Pages & Login
package/rules/npm-yarn.md CHANGED
@@ -30,19 +30,31 @@ description: NPM & Yarn patterns
30
30
 
31
31
  # Consistent versions
32
32
 
33
- In Monorepos pin versions of sub-packages to main.
33
+ In monorepos pin versions of sub-packages to the root; these packages cause issues when versions drift.
34
34
 
35
- https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332
36
- https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
35
+ https://github.com/raineorshine/npm-check-updates/issues/1332#issuecomment-1717862332 https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides
37
36
 
38
37
  Root `package.json`:
39
38
 
40
39
  ```json
41
40
  {
42
41
  "overrides": {
42
+ "@types/node": "$@types/node",
43
+ "@types/react": "$@types/react",
44
+ "@types/react-dom": "$@types/react-dom",
43
45
  "next": "$next",
44
46
  "eslint": "$eslint",
45
- "typescript": "$typescript"
47
+ "typescript": "$typescript",
48
+ "vite": "$vite"
49
+ },
50
+ "resolutions": {
51
+ "@types/node": "^26",
52
+ "@types/react": "^19",
53
+ "@types/react-dom": "^19",
54
+ "eslint": "^10",
55
+ "next": "^16",
56
+ "typescript": "^6",
57
+ "vite": "^8"
46
58
  }
47
59
  }
48
60
  ```
@@ -52,12 +64,26 @@ All other `package.json`:
52
64
  ```jsonc
53
65
  {
54
66
  "devDependencies": {
55
- "next": "16.0.0", // except next, see nextjs.md
56
- "typescript": "*", // vividly express version does not matter
67
+ "next": "^16.0.0", // except next, see nextjs.md
68
+ "typescript": "^6.0.0",
57
69
  },
58
70
  }
59
71
  ```
60
72
 
73
+ Yarn does not apply npm `overrides`; `defineYarnConfig` reads them as constraints together with `resolutions`, keeps non-peer leaf ranges equal, and falls back to the listed default packages when `overrides` is absent.
74
+
75
+ Every package with `"packageManager": "yarn@..."` MUST directly install `@yarnpkg/types` and use:
76
+
77
+ ```js
78
+ /** @type {import('@yarnpkg/types')} */
79
+ const { defineConfig } = require('@yarnpkg/types');
80
+ const { defineYarnConfig } = require('@kirill.konshin/lint/yarn');
81
+
82
+ module.exports = defineConfig(defineYarnConfig());
83
+ ```
84
+
85
+ Run `yarn constraints --fix` after dependency changes.
86
+
61
87
  # `.yarnrc.yml`
62
88
 
63
89
  Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json` and Corepack.
@@ -78,3 +104,22 @@ npmMinimalAgeGate: 0
78
104
  npmPreapprovedPackages:
79
105
  - '@kirill.konshin/*'
80
106
  ```
107
+
108
+ # Yalc (Local Package Linking)
109
+
110
+ Test unpublished packages in sibling projects (yalc is a root devDependency here):
111
+
112
+ 1. `yarn nx run @kirill.konshin/<pkg>:build`
113
+ 2. `cd packages/<pkg> && yarn yalc publish` (after changes: `yarn yalc publish --push` updates all linked consumers)
114
+ 3. In the consumer: `npx yalc link @kirill.konshin/<pkg>` (or the yalc binary from this repo)
115
+
116
+ Rules:
117
+
118
+ - ALWAYS use `yalc link` (symlink mode: `node_modules/<pkg>` → local `.yalc/<pkg>` copy), NEVER `yalc add` — `add` writes `file:.yalc/...` into package.json
119
+ - While linked, `package.json`, `yarn.lock` and `.yarnrc.yml` MUST NOT be modified by the link — link artifacts break CI/other machines and must NEVER be committed; gitignore `.yalc/` and `yalc.lock` in the consumer
120
+ - The real dependency (e.g. `"@kirill.konshin/auth": "^0.0.1"`) is committed separately; the consumer's `yarn.lock` can only be updated after the version is actually published to npm
121
+ - The consumer resolves the linked package's own dependencies from its node_modules — they must be installed there (usually already are as the consumer's own deps)
122
+ - A later `yarn install` in the consumer removes the symlink — re-run `yalc link`
123
+ - Unlinking: `yalc remove --all` cleans `.yalc/` and `yalc.lock` but leaves dangling symlinks in `node_modules` — delete them before `yarn install`
124
+ - Yarn 4.17+ quarantines packages published <24h ago (`npmMinimalAgeGate`) — consumers need `npmPreapprovedPackages: ["@kirill.konshin/*"]` in `.yarnrc.yml` to install own packages right after release (older Yarn errors on that key — upgrade the consumer via `packageManager` first)
125
+ - `.yarnrc.local.yml` is NOT a thing (open Yarn feature request, local overrides only via `YARN_*` env vars) and yalc runs NO registry (it is a file store in `~/.yalc`), so a registry override cannot replace linking — `yalc link` is the only mode that leaves all manifests untouched
package/rules/nx.md CHANGED
@@ -23,9 +23,9 @@ paths:
23
23
  - Commit changes to root `package.json` or `yarn.lock` or `nx.json` ONLY as `chore` otherwise ALL packages will be bumped
24
24
  - https://github.com/nrwl/nx/issues/34542 (root file changes → all bumped)
25
25
  - NX Release attributes commits to projects by FILE PATHS via `nx affected` against the CURRENT graph — commit scope (`feat(pkg):`) does not limit attribution
26
- - NEVER fully delete (or `nx g move`-rename) a package: a historical `feat`/`fix` that touched a `package.json`/`project.json` which no longer exists on disk is attributed to ALL projects, and mass-bumps the whole workspace on the very next release run (even a `chore` push);
27
- - ALWAYS leave a tombstone `package.json` at the EXACT old path (`private: true`, no scripts), and exclude it in `release.projects` (`!packages/<retired>`) so it's never versioned/published;
28
- - removable only once EVERY package has a tag newer than the last `feat`/`fix` that touched the retired `package.json`;
29
- - moving the tombstone elsewhere breaks it — the check is on the historical file path
30
- - https://github.com/nrwl/nx/issues/33374 (delete/rename → all released)
31
- - https://github.com/nrwl/nx/issues/34277 (scans too much, slow, warnings for removed)
26
+ - NX ≥ 23.2 (23.2.0-beta.5+): deleted projects no longer affect all projects during RELEASE attribution (https://github.com/nrwl/nx/pull/36538) — packages can be deleted/renamed freely, no tombstones needed; commit the deletion as `chore:` (generic `nx affected` keeps the conservative "deleted → all affected" fallback)
27
+ - NX < 23.2: NEVER fully delete (or `nx g move`-rename) a package — a historical `feat`/`fix` that touched a `package.json`/`project.json` which no longer exists on disk is attributed to ALL projects, and mass-bumps the whole workspace on the very next release run (even a `chore` push) — https://github.com/nrwl/nx/issues/33374
28
+ - leave a tombstone `package.json` at the EXACT old path (`private: true`, no scripts), and exclude it in `release.projects` (`!packages/<retired>`) so it's never versioned/published;
29
+ - removable once EVERY package has a tag newer than the last `feat`/`fix` that touched the retired `package.json` — or after upgrading to NX ≥ 23.2;
30
+ - moving the tombstone elsewhere breaks it — the check is on the historical file path
31
+ - https://github.com/nrwl/nx/issues/34277 (scans too much, slow, warnings for removed) — still open
@@ -25,7 +25,9 @@ paths:
25
25
  - `isolatedDeclarations: true`: USE ONLY FOR PUBLISHED LIBRARIES, enables faster declaration emit and requires explicit type annotations on exports
26
26
  - In such case all exported functions and variables must have explicit type annotations:
27
27
  - `strictNullChecks: true`: Null and undefined are distinct types
28
- - `moduleResolution: "bundler"`
28
+ - `moduleResolution: "bundler"`: MANDATORY for ALL TypeScript projects, no exceptions — never `node16`/`nodenext`/`node10`
29
+ - Keeps import specifiers extensionless (`next/link`, `./file`), which is what every bundler and every modern runtime target expects; `node16`/`nodenext` would force `.js` suffixes on source that never runs through Node's own resolver
30
+ - Requires `module: "esnext"` (or `preserve`) — `bundler` is rejected with CommonJS-emitting `module` settings
29
31
  - `jsx: "react-jsx"`: Modern JSX transform (no React default import needed)
30
32
 
31
33
  # File Structure
@@ -79,14 +81,18 @@ paths:
79
81
  6. Local CSS (e.g. `./styles.css`)
80
82
  - Side-effect imports (polyfills, CSS) are sorted into their group too; the linter only keeps the written order of multiple side-effect imports landing in the _same_ group, so sequence order-dependent ones yourself
81
83
 
84
+ # Published Libraries
85
+
86
+ - Publish ESM ONLY — NEVER add a `require` condition or a CJS build; the sole exception is a file a tool can only load as CJS (`@kirill.konshin/lint`'s `./yarn` entry, forced by Yarn constraints), which ships as an explicit `.cjs` with its own `.d.cts`
87
+ - `exports` conditions must be FLAT and `types`-first (`{types, import, default}`) — a nested or `import`-only map matches NO condition outside `import`, so CJS resolvers get `ERR_PACKAGE_PATH_NOT_EXPORTED` (the entry is invisible, not merely interop-incompatible); `default` is the catch-all, not a CJS build, and Node >= 22.12 loads the ESM behind it through `require()`
88
+ - Next.js transpiles `next.config.ts` to CommonJS and `require()`s it, so config-only helpers MUST be reachable this way — keep them in their own subpath that imports nothing at runtime
89
+ - Every subpath export needs its OWN bundler entry — a pure re-export barrel that is merely reachable from the main entry gets inlined, and its `dist/<mod>/index.js` is never written
90
+ - NEVER import an OPTIONAL peerDependency at runtime, not even for a single constant — inline it (annotate with `typeof` of a type-only import as a drift guard); a barrel re-exporting such a module makes the WHOLE entry unresolvable when the peer is absent
91
+
82
92
  # Type Annotation Patterns
83
93
 
84
- - Use `interface` only for declaration merging/augmentation (e.g. extending a third-party global
85
- interface) - a class can `implements` a `type` alias just as well, so that's not a reason to reach
86
- for `interface`
87
- - This is enforced by lint (`@typescript-eslint/consistent-type-definitions`), which can't special-case
88
- augmentation - when it's genuinely needed, add
89
- `// eslint-disable-next-line @typescript-eslint/consistent-type-definitions` above the `interface`
94
+ - Use `interface` only for declaration merging/augmentation (e.g. extending a third-party global interface) - a class can `implements` a `type` alias just as well, so that's not a reason to reach for `interface`
95
+ - This is enforced by lint (`@typescript-eslint/consistent-type-definitions`), which can't special-case augmentation - when it's genuinely needed, add `// eslint-disable-next-line @typescript-eslint/consistent-type-definitions` above the `interface`
90
96
  - Prefer to inline types into function signature or variable declarations
91
97
  - Introduce types when reused or complex. Avoid creating a type for every single thing
92
98
  - Try to reuse types that exist in project (e.g. redux state, zod schema, component props, final function signature can have one shared type + derivatives like `Omit<>`, `Partial<>` etc.)
package/rules/webstorm.md CHANGED
@@ -177,3 +177,23 @@ Applies if project is using Tailwind.
177
177
  </component>
178
178
  </project>
179
179
  ```
180
+
181
+ # Configure `indexLayout.xml`
182
+
183
+ Ban build directories from search using examples:
184
+
185
+ ```xml
186
+ <?xml version="1.0" encoding="UTF-8"?>
187
+ <project version="4">
188
+ <component name="UserContentModel">
189
+ <attachedFolders />
190
+ <explicitIncludes>
191
+ </explicitIncludes>
192
+ <explicitExcludes>
193
+ <Path>path-to-eve/.eve</Path>
194
+ <Path>path-to-vite/dist</Path>
195
+ <Path>path-to-next/.next</Path>
196
+ </explicitExcludes>
197
+ </component>
198
+ </project>
199
+ ```
package/index.d.ts DELETED
@@ -1,281 +0,0 @@
1
- /*
2
- * Hand-written declarations for the raw-JS package (see README "Why raw JS" - there is no build to
3
- * emit them from). Keep in sync with index.js / configs/*.js and their JSDoc.
4
- *
5
- * Types are pulled from the real underlying packages wherever they export them (eslint's
6
- * `Linter.Config`, eslint-plugin-tailwindcss's `PluginSettings`, prettier's `Config`,
7
- * lint-staged's `Configuration`, the plugins' own default-export types), so the options here stay
8
- * in sync with how the tools themselves define their configs. `@next/eslint-plugin-next` exports
9
- * no settings type - `NextOptions.rootDir` mirrors its documented `settings.next.rootDir` schema.
10
- */
11
- import type { ParserOptions as TsParserOptions } from '@typescript-eslint/parser';
12
- import type { Linter } from 'eslint';
13
- import type { PluginSettings as TailwindPluginSettings } from 'eslint-plugin-tailwindcss';
14
- import type { Configuration as LintStagedConfiguration } from 'lint-staged';
15
- import type { Config as PrettierConfig } from 'prettier';
16
-
17
- type ProjectServiceOptions = Exclude<NonNullable<TsParserOptions['projectService']>, boolean>;
18
-
19
- /**
20
- * Base shape of every tool's options object. Using the object form implies the tool is ON -
21
- * `enabled` defaults to `true`, so a partially configured tool doesn't also need a separate
22
- * `true` anywhere; set `enabled: false` to force it off while keeping the other options in place.
23
- */
24
- export type ToggleOptions = {
25
- enabled?: boolean;
26
- };
27
-
28
- /**
29
- * Detection behavior ({@link defineLintConfig} `detection`) - the same toggle notation as the
30
- * tool flags:
31
- * - `undefined` / `true` / `{}` - tools default ON via full auto-detection
32
- * - `false` / `{ enabled: false }` - tools default OFF; explicitly enabled tools still
33
- * auto-detect their settings
34
- * - `strict: true` - same-scope package probes only (exactly what the `has*` checks are): no
35
- * evidence scans; mandatory settings like `cssConfigPath` must be explicit, and `nx.json` is
36
- * checked at cwd instead of the workspace root. `{ enabled: false, strict: true }` is ideal for
37
- * per-package monorepo configs.
38
- */
39
- export type DetectionOptions = ToggleOptions & {
40
- /** same-scope package probes only - no workspace evidence scans */
41
- strict?: boolean;
42
- };
43
-
44
- /** Options for the Next.js blocks ({@link nextBaseConfig}). */
45
- export type NextOptions = ToggleOptions & {
46
- /**
47
- * Root of the Next.js app(s) for `@next/eslint-plugin-next` (`settings.next.rootDir`) - needed
48
- * when the apps don't live at the workspace root, e.g. `path/to/next-app` (globs are supported
49
- * by the plugin; pass the package root, not `src` - the plugin resolves both the `pages`/`app`
50
- * and `src/pages`/`src/app` layouts from it). When omitted, auto-detected via
51
- * {@link findNextRoots}: no evidence found → no settings (the setting is optional), several
52
- * apps → all of them as an array.
53
- *
54
- * @see https://nextjs.org/docs/app/api-reference/config/eslint
55
- */
56
- rootDir?: string | string[];
57
- };
58
-
59
- /** Options for the Tailwind block ({@link tailwindConfig}). */
60
- export type TailwindOptions = ToggleOptions & {
61
- /**
62
- * Tailwind v4 entry CSS for `eslint-plugin-tailwindcss` (`settings.tailwindcss.cssConfigPath`),
63
- * absolute or relative to the lint working directory. When omitted, auto-detected via
64
- * {@link findTailwindEntry}.
65
- */
66
- cssConfigPath?: TailwindPluginSettings['cssConfigPath'];
67
- /**
68
- * Scope the Tailwind rules to the workspace package that owns the entry CSS (emitted as the
69
- * block's `basePath`, ESLint >= 9.30) instead of the whole workspace. No-op when the entry is
70
- * owned by the workspace root itself (single-package repo, or not inside a declared
71
- * workspace package).
72
- *
73
- * @default true
74
- */
75
- scoped?: boolean;
76
- };
77
-
78
- /**
79
- * Options for the type-aware block ({@link typeAwareConfig}). `allowDefaultProject` and
80
- * `maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING` are typescript-eslint's own
81
- * `projectService` options (real types). `allowDefaultProject` has NO default - generate the file
82
- * list with {@link scanWorkspace} (absolute entries are relativized against `tsconfigRootDir`
83
- * automatically); the match cap defaults to that list's length when it is given (set it explicitly
84
- * when using multi-match globs); `tsconfigRootDir` defaults to the detected workspace root.
85
- */
86
- export type TypeAwareOptions = ToggleOptions &
87
- Pick<
88
- ProjectServiceOptions,
89
- 'allowDefaultProject' | 'maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING'
90
- > & {
91
- /** Defaults to {@link findWorkspaceRoot}. */
92
- tsconfigRootDir?: TsParserOptions['tsconfigRootDir'];
93
- };
94
-
95
- /** Options for the default-ignore block ({@link defaultIgnoreConfig}). */
96
- export type DefaultIgnoreOptions = ToggleOptions & {
97
- /**
98
- * `import.meta.url` of the consumer's `eslint.config.mjs` - the `.gitignore` and
99
- * `.prettierignore` files are resolved next to it. Required: the config file location cannot
100
- * be auto-detected.
101
- */
102
- importMetaUrl: string;
103
- };
104
-
105
- /**
106
- * Per-tool toggles for {@link defineLintConfig}. Every flag is optional:
107
- * - `undefined` (default) - auto-detect via the corresponding `has*` export
108
- * - `true` or an options object - force the tool's blocks ON (use when detection misses a tool
109
- * that lives only in leaf packages of a monorepo); in the object form `enabled` defaults to
110
- * `true` and can be set to `false` to force OFF while keeping the other options in place
111
- * - `false` - force OFF
112
- *
113
- * The gated `*Config()` block functions accept the same flag value directly.
114
- */
115
- export type LintOptions = {
116
- /** Detection behavior: default tool state + strict mode; see {@link DetectionOptions} */
117
- detection?: boolean | DetectionOptions;
118
- /** Next.js (`eslint-config-next`); when off, generic React/JSX rules apply instead */
119
- next?: boolean | NextOptions;
120
- /** Storybook (`eslint-plugin-storybook`) */
121
- storybook?: boolean | ToggleOptions;
122
- /** Turborepo (`eslint-plugin-turbo`) */
123
- turbo?: boolean | ToggleOptions;
124
- /** Nx (`@nx/eslint-plugin` base + `@nx/dependency-checks`) */
125
- nx?: boolean | ToggleOptions;
126
- /** Jest recommended rules for `*.{test,spec}.*` */
127
- jest?: boolean | ToggleOptions;
128
- /** Vitest recommended rules for `*.{test,spec}.*` */
129
- vitest?: boolean | ToggleOptions;
130
- /** Tailwind (`eslint-plugin-tailwindcss`); forcing ON without a resolvable entry CSS is a hard error, several entry CSS candidates always are */
131
- tailwind?: boolean | TailwindOptions;
132
- /** Type-aware TypeScript rules; off by default (slow), nothing to auto-detect */
133
- typeAware?: boolean | TypeAwareOptions;
134
- /** `.gitignore` + `.prettierignore` as ESLint ignores; off by default, `true` without `importMetaUrl` is a hard error */
135
- defaultIgnore?: boolean | DefaultIgnoreOptions;
136
- };
137
-
138
- /**
139
- * Build the shared flat ESLint config. By default every tool integration is auto-detected (see the
140
- * `has*` exports); pass {@link LintOptions} to force any of them on/off or to supply tool-specific
141
- * settings. ESLint natively awaits a Promise default export, so a plain
142
- * `export default defineLintConfig({...})` works; `await` it only when composing with extra blocks.
143
- */
144
- export function defineLintConfig(
145
- options?: LintOptions | Promise<LintOptions> | (() => LintOptions | Promise<LintOptions>),
146
- ): Promise<Linter.Config[]>;
147
-
148
- // ----- Blocks (in the order defineLintConfig applies them; from configs/*.js) -----
149
- // Gated blocks take their LintOptions flag and return [] when resolved off.
150
-
151
- /** Core JS recommended rules, global ignores, browser + Node globals, and core-rule overrides. */
152
- export function baseConfig(): Linter.Config[];
153
- /**
154
- * `.gitignore` + `.prettierignore` (next to the consumer's config file, both must exist) as
155
- * ESLint ignores. Off by default; enabling without `importMetaUrl` is a hard error.
156
- */
157
- export function defaultIgnoreConfig(option?: boolean | DefaultIgnoreOptions): Linter.Config[];
158
- /** The whole `eslint-config-next` flat config, plus `settings.next.rootDir` when given. Next-only, ungated. */
159
- export function nextBaseConfig(options?: NextOptions): Promise<Linter.Config[]>;
160
- /** React/React Hooks/jsx-a11y rules for non-Next (e.g. Vite) React projects. Ungated. */
161
- export function reactBaseConfig(): Linter.Config[];
162
- /** Chooser: {@link nextBaseConfig} when Next is enabled, the {@link reactBaseConfig} fallback otherwise. */
163
- export function nextConfig(option?: boolean | NextOptions, strict?: boolean): Promise<Linter.Config[]>;
164
- /**
165
- * The whole React family in its load-bearing order - {@link nextConfig} (Next is just a shortcut
166
- * to an opinionated React/TypeScript setup), then {@link typescriptOverridesConfig},
167
- * {@link nextOverridesConfig} and {@link reactSettingsConfig}, which apply no matter whether Next
168
- * or plain React won. Used by {@link defineLintConfig}; `option` is the `next` flag.
169
- */
170
- export function reactConfig(option?: boolean | NextOptions, strict?: boolean): Promise<Linter.Config[]>;
171
- /** `eslint-config-next/typescript` (typescript-eslint wiring, which stems from Next) + deliberate rule overrides. */
172
- export function typescriptOverridesConfig(): Linter.Config[];
173
- /** Overrides of rules set by `eslint-config-next` (always applied, harmless without Next). */
174
- export function nextOverridesConfig(): Linter.Config[];
175
- /** React version settings workaround (ESLint 10 + Next). Always applied. */
176
- export function reactSettingsConfig(): Linter.Config[];
177
- /** Prettier compatibility (`eslint-config-prettier/flat`). */
178
- export function prettierConfig(): Linter.Config[];
179
- /** Storybook recommended rules. */
180
- export function storybookConfig(option?: boolean | ToggleOptions, strict?: boolean): Promise<Linter.Config[]>;
181
- /** eslint-plugin-import-x recommended rules + overrides + the default-export relaxation for conventional files. */
182
- export function importXConfig(): Linter.Config[];
183
- /** Deterministic import ordering (eslint-plugin-simple-import-sort). */
184
- export function importSortConfig(): Linter.Config[];
185
- /** Autofixable removal of unused imports. */
186
- export function unusedImportsConfig(): Linter.Config[];
187
- /** eslint-plugin-promise recommended rules + overrides. */
188
- export function promiseConfig(): Linter.Config[];
189
- /** Filename casing + node: protocol (two hand-picked unicorn rules). */
190
- export function unicornConfig(): Linter.Config[];
191
- /** Type-aware rules via typescript-eslint's projectService; off unless the flag is set (nothing to auto-detect). */
192
- export function typeAwareConfig(option?: boolean | TypeAwareOptions, strict?: boolean): Linter.Config[];
193
- /** Turborepo rules. */
194
- export function turboConfig(option?: boolean | ToggleOptions): Promise<Linter.Config[]>;
195
- /**
196
- * Tailwind recommended rules. Explicit `cssConfigPath` wins; otherwise auto-found via
197
- * {@link findTailwindEntry}. Zero entries: inert when auto-detected, throws when forced on
198
- * (`true`/options). Several entries ALWAYS throw - pass `cssConfigPath` to pick one.
199
- */
200
- export function tailwindConfig(option?: boolean | TailwindOptions, strict?: boolean): Promise<Linter.Config[]>;
201
- /** Nx plugin registration + `@nx/dependency-checks`. */
202
- export function nxConfig(option?: boolean | ToggleOptions, strict?: boolean): Promise<Linter.Config[]>;
203
- /** Jest recommended rules, scoped to test files. */
204
- export function jestConfig(option?: boolean | ToggleOptions, strict?: boolean): Linter.Config[];
205
- /** Vitest recommended rules + globals, scoped to test files. */
206
- export function vitestConfig(option?: boolean | ToggleOptions, strict?: boolean): Linter.Config[];
207
- /** Runner-agnostic test rules (consistent-test-it, test colocation). Always applied. */
208
- export function testConfig(): Linter.Config[];
209
-
210
- // ----- Detection (module-load time capability probes, exported for debugging; from lib.js) -----
211
-
212
- /**
213
- * Workspace root of the consumer project - the anchor for every config-file scan and for `nx.json`
214
- * detection. Resolved from the package manager (env: Yarn Berry `PROJECT_CWD` / npm
215
- * `npm_config_local_prefix`; CLIs: `pnpm root -w`, Yarn Berry via `yarn node`, `npm prefix`),
216
- * falling back to a lockfile walk bounded by `.git`; every candidate must contain `cwd`.
217
- * Cached per `cwd`.
218
- */
219
- export function findWorkspaceRoot(cwd?: string): string;
220
-
221
- export const hasNext: boolean;
222
- export const hasStorybook: boolean;
223
- export const hasVite: boolean;
224
- export const hasJest: boolean;
225
- export const hasVitest: boolean;
226
- export const hasTurbo: boolean;
227
- export const hasNx: boolean;
228
- export const hasTailwind: boolean;
229
-
230
- // ----- Extension lists (from lib.js) -----
231
-
232
- export const tsExtsRaw: string;
233
- export const eslintExtsRaw: string;
234
- export const prettierExtsRaw: string;
235
- export const tsExts: string;
236
- export const eslintExts: string;
237
- export const prettierExts: string;
238
-
239
- // ----- Plugin re-exports (detection-gated at module load; null when the tool wasn't detected) -----
240
-
241
- export const nextPlugin: typeof import('@next/eslint-plugin-next').default | null;
242
- export const nxPlugin: typeof import('@nx/eslint-plugin').default | null;
243
- export const turboPlugin: typeof import('eslint-plugin-turbo').default | null;
244
- export const jestPlugin: typeof import('eslint-plugin-jest');
245
- export const vitestPlugin: typeof import('@vitest/eslint-plugin').default;
246
-
247
- // ----- Helpers & companion configs -----
248
-
249
- /**
250
- * Auto-find the Tailwind v4 entry CSS: the single `*.css` (scanned across the workspace root and
251
- * every workspace package, skipping `.gitignore`d files and build outputs) containing
252
- * `@import "tailwindcss"`; null when zero or several match.
253
- */
254
- export function findTailwindEntry(ignores: string[]): string | null;
255
-
256
- /**
257
- * Auto-find Next.js app roots (scanned across the workspace root and every workspace package,
258
- * skipping `.gitignore`d files and build outputs). `next.config.*` is optional in Next.js, so any of three
259
- * signals marks an app root: a `next.config.*`, a `package.json` depending on `next`
260
- * (dependencies/devDependencies - peer declarations mark libraries, not apps), or a
261
- * `src/app`/`src/pages` directory (the reported root is the directory containing `src`);
262
- * deduplicated and sorted.
263
- */
264
- export function findNextRoots(ignores: string[]): string[];
265
-
266
- /**
267
- * Glob for config-file candidates across the workspace - the root directory plus every workspace
268
- * package (the real `workspaces` globs, not a depth heuristic) - skipping dot dirs unless `dot`,
269
- * build outputs, extra `ignores` and everything in the root `.gitignore`.
270
- * Returns absolute paths - useful for building file lists like `typeAware.allowDefaultProject`.
271
- */
272
- export function scanWorkspace(fileGlob: string, ignores?: string[], options?: { dot?: boolean }): string[];
273
-
274
- /** Convert an ignore file (`.gitignore`, `.prettierignore`) into an ESLint ignores block. */
275
- export function includeIgnoreFile(importMetaUrl: string, ignoreFile: string): Linter.Config;
276
-
277
- /** Shared Prettier configuration (`.prettierrc.mjs`: `export default prettier`). */
278
- export const prettier: PrettierConfig;
279
-
280
- /** Shared lint-staged configuration (`.lintstagedrc.mjs`: `export default listStaged`). */
281
- export const listStaged: LintStagedConfiguration;