exadev-eslint-config 2.19.0 → 2.19.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 +137 -86
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,19 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
> A real ESLint plugin (not a shareable config) exposing custom rules shared across ExaDev projects. Also published under the unscoped alias `exadev-eslint-config`.
|
|
6
6
|
|
|
7
|
+
**Contents:** [Why](#why) · [Getting started](#getting-started) · [The lighter option](#the-lighter-option-the-plugin-named-export) · [Optional features](#optional-features) · [Rules](#rules) · [Barrel policy](#barrel-policy) · [Development](#development) · [License](#license)
|
|
8
|
+
|
|
7
9
|
## Why
|
|
8
10
|
|
|
9
11
|
Multiple ExaDev repos carried identical copies of a handful of custom ESLint rules (barrel/index discipline, re-export placement, pointless-alias detection). This package is the single source of truth for those rules. Only the *rules* are centralized — not a consumer's whole `eslint.config.ts`, since file-scoping, tsconfig wiring, and runtime-isomorphism import bans are genuinely project-specific. Each consumer keeps its own `eslint.config.ts`, importing rule implementations from here.
|
|
10
12
|
|
|
11
13
|
## Getting started
|
|
12
14
|
|
|
13
|
-
Consumers need `eslint >=10.0.0` and `typescript-eslint >=8.0.0` as required peer dependencies. Importing anything from this package resolves `typescript-eslint`, since both the default export and `plugin` share the same root module — ESM/CJS module evaluation runs a module's entire top-level import graph regardless of which export the caller reads (see [Architecture](#architecture)).
|
|
14
|
-
|
|
15
15
|
```sh
|
|
16
16
|
pnpm add -D @exadev/eslint-config typescript-eslint eslint
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Requires `eslint >=10.0.0` and `typescript-eslint >=8.0.0` as peer dependencies. Importing anything from this package resolves `typescript-eslint`, since the default export and the `plugin` named export share one root module — see [Architecture](#architecture).
|
|
20
20
|
|
|
21
21
|
```ts
|
|
22
22
|
// eslint.config.ts
|
|
@@ -34,18 +34,57 @@ export default tseslint.config(
|
|
|
34
34
|
);
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
**
|
|
37
|
+
**Remove your own `tseslint.configs.recommended`/`recommendedTypeChecked`/`strictTypeChecked`/`stylisticTypeChecked` spreads.** The default export already includes `strictTypeChecked` (which subsumes both plain `recommended` and `recommendedTypeChecked`) plus `stylisticTypeChecked`, and registers the `@typescript-eslint` plugin/parser itself — flat config rejects two different plugin object instances registered under the same namespace. You still supply your own `languageOptions.parserOptions.project`/`projectService` pointing at your tsconfig(s).
|
|
38
38
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
39
|
+
### What the default export includes
|
|
40
|
+
|
|
41
|
+
**typescript-eslint presets:**
|
|
42
|
+
|
|
43
|
+
- `strictTypeChecked` + `stylisticTypeChecked` — already covers `no-deprecated`, `no-misused-spread`, `no-mixed-enums`, `no-unnecessary-condition`, `use-unknown-in-catch-callback-variable`, `return-await`, `related-getter-setter-pairs`, `no-unnecessary-type-parameters`, and more (not re-listed individually below).
|
|
44
|
+
|
|
45
|
+
**This package's own rules** (full details in [Rules](#rules)):
|
|
43
46
|
|
|
44
|
-
|
|
47
|
+
- `exadev/barrel-policy` at its auto-detecting default — see [Barrel policy](#barrel-policy)
|
|
48
|
+
- `exadev/no-object-assign`
|
|
49
|
+
- `exadev/no-mutable-union-array-param`
|
|
50
|
+
- `exadev/no-array-isarray-mutation`
|
|
51
|
+
- `exadev/no-enum-number-widening`
|
|
52
|
+
- `exadev/no-enum-reverse-lookup-widening`
|
|
53
|
+
- `exadev/no-map-instanceof-mutation`
|
|
54
|
+
- `exadev/no-set-instanceof-mutation`
|
|
55
|
+
- `exadev/prefer-readonly-array-param`
|
|
56
|
+
- `exadev/prefer-readonly-object-param`
|
|
57
|
+
- `exadev/prefer-numeric-sort-compare`
|
|
58
|
+
- `exadev/no-pointless-reassignment`
|
|
59
|
+
- `exadev/test-file-kind`
|
|
45
60
|
|
|
46
|
-
**
|
|
61
|
+
**Individual rule tuning**, with the reasoning for each:
|
|
47
62
|
|
|
48
|
-
|
|
63
|
+
- `linterOptions.noInlineConfig` — no `eslint-disable` comments of any kind.
|
|
64
|
+
- `@typescript-eslint/consistent-type-assertions` — bans all type assertions (relaxed in test files, see below).
|
|
65
|
+
- `@typescript-eslint/consistent-type-imports` and `@typescript-eslint/consistent-type-exports`.
|
|
66
|
+
- `@typescript-eslint/consistent-return` — a function that implicitly returns `undefined` on one path and a real value on another is usually a bug, not a deliberate design.
|
|
67
|
+
- `@typescript-eslint/no-non-null-assertion` — bans the `!` operator, the same manual-override escape hatch as a type assertion under a different spelling.
|
|
68
|
+
- `@typescript-eslint/no-redeclare` and `@typescript-eslint/no-shadow`.
|
|
69
|
+
- `@typescript-eslint/no-use-before-define` set to `{ functions: false }` — a genuine temporal-dead-zone crash risk for `let`/`const`/`class`/enum bindings, but function declarations are fully hoisted and safe to call before their point of textual declaration; this codebase's own rule files consistently define helper functions after the logic that calls them.
|
|
70
|
+
- `@typescript-eslint/ban-ts-comment` — bans `@ts-expect-error` outright (relaxed in test files, see below).
|
|
71
|
+
- `@typescript-eslint/method-signature-style` set to `'property'` — method-shorthand signatures are checked bivariantly under `strictFunctionTypes`, which is unsound.
|
|
72
|
+
- `@typescript-eslint/prefer-readonly`, `@typescript-eslint/promise-function-async`, `@typescript-eslint/require-array-sort-compare`.
|
|
73
|
+
- `@typescript-eslint/strict-void-return` — not yet in any typescript-eslint preset. Disallows passing a value-returning function where a void-returning one is expected (e.g. `arr.forEach(x => otherArray.push(x))`), which typechecks today only because of TS's own void-return contravariance leniency.
|
|
74
|
+
- `@typescript-eslint/switch-exhaustiveness-check`.
|
|
75
|
+
- `@typescript-eslint/strict-boolean-expressions` at the rule's own bare defaults — an unambiguous non-nullable truthy check stays allowed; an ambiguous nullable check does not.
|
|
76
|
+
- `@typescript-eslint/no-magic-numbers` — tuned to exempt array indexes, enum members, readonly class properties, default parameter values, numeric literal types (e.g. `type Indent = 2 | 4`), and the handful of universally-idiomatic bare numbers (`-1`, `0`, `1`, `2`).
|
|
77
|
+
- `max-lines` set to `{ max: 800, skipBlankLines: true, skipComments: true }` — counts only real code, so a file isn't pushed over the limit by whitespace or its own WHY-explanation comments.
|
|
78
|
+
- `no-warning-comments` — bans any comment containing `Stryker disable` (Stryker's own mutation-testing suppression directive, invisible to `noInlineConfig` above since it isn't an eslint-disable comment).
|
|
79
|
+
|
|
80
|
+
**Test files** (`**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`) get two narrow relaxations of this package's own additions, and only these two:
|
|
81
|
+
|
|
82
|
+
- `@ts-expect-error` reverts to `allow-with-description` — a compile-time-only assertion of a type failure is a legitimate test pattern; `@ts-ignore`/`@ts-nocheck` stay banned since `@ts-expect-error` is strictly better.
|
|
83
|
+
- `consistent-type-assertions` relaxes to `assertionStyle: 'as'` — the legacy `<Type>value` form stays banned everywhere.
|
|
84
|
+
|
|
85
|
+
Nothing else inherited from the presets is relaxed.
|
|
86
|
+
|
|
87
|
+
## The lighter option: the `plugin` named export
|
|
49
88
|
|
|
50
89
|
For a project that wants only this package's own rules without the full type-checked bundle, import the named `plugin` export and wire rules individually:
|
|
51
90
|
|
|
@@ -99,42 +138,18 @@ export default tseslint.config(
|
|
|
99
138
|
);
|
|
100
139
|
```
|
|
101
140
|
|
|
102
|
-
|
|
141
|
+
`plugin.configs.recommended`/`plugin.configs.barrel` carry no `files`/`ignores` and are safe unscoped — `no-side-effects-in-index` and `no-non-barrel-reexport` each check `context.filename` themselves (self-scoping). For a barrel not at `src/index.ts`, or a project-specific exception, layer an override on top (e.g. `{ files: ['lib/other.ts'], rules: { 'exadev/no-non-barrel-reexport': 'off' } }`) rather than wiring all four rules individually.
|
|
103
142
|
|
|
104
|
-
## Optional
|
|
143
|
+
## Optional features
|
|
105
144
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
```
|
|
113
|
-
If none of these resolve, `@exadev/eslint-config`'s default export is byte-for-byte identical to the plain TypeScript ruleset — nothing about the base package changes.
|
|
114
|
-
2. **For React specifically, the file must actually be `.jsx`/`.tsx`.** The React/hooks/a11y rule block is scoped to `files: ['**/*.jsx', '**/*.tsx']`, so even if `eslint-plugin-react` is resolvable only incidentally (e.g. hoisted as a transitive dependency of something unrelated in a monorepo, with zero real JSX anywhere in the linted project), its rules are never matched against a file that isn't JSX — ESLint's flat-config `files` matching happens per linted file, at lint time, not at config-build time. `@next/eslint-plugin-next`'s block carries no such glob: its own presence is already an unambiguous signal on its own (nothing installs it except a real Next.js project).
|
|
115
|
-
|
|
116
|
-
React support pairs `eslint-plugin-react`'s `flat/recommended` with its own `flat/jsx-runtime` config, which turns `react/react-in-jsx-scope` and `react/jsx-uses-react` back off. `flat/recommended` alone assumes the classic runtime, where every file using JSX needs `import React` in scope; the automatic JSX runtime, the default since React 17 and the only mode Next.js's own compiler supports, needs no such import. Without this pairing, a consumer on the automatic runtime would see `react/react-in-jsx-scope` fire on every JSX file in the project.
|
|
117
|
-
|
|
118
|
-
### Explicit control
|
|
119
|
-
|
|
120
|
-
Two ways to override the automatic behaviour, for anyone who doesn't want to rely on it:
|
|
121
|
-
|
|
122
|
-
**`plugin.configs.react`/`plugin.configs.nextjs`** — explicit tier selection, mirroring `plugin.configs.recommended`/`.barrel`. Unlike those two, which only ever reference this package's own always-present rules, selecting `configs.react`/`.nextjs` is itself an explicit request: it **throws** a clear, actionable error if the underlying peer isn't installed, rather than silently returning nothing.
|
|
123
|
-
```ts
|
|
124
|
-
import { plugin } from '@exadev/eslint-config';
|
|
125
|
-
import tseslint from 'typescript-eslint';
|
|
126
|
-
|
|
127
|
-
export default tseslint.config(
|
|
128
|
-
// ...your own config...
|
|
129
|
-
{
|
|
130
|
-
files: ['**/*.tsx'],
|
|
131
|
-
plugins: { exadev: plugin },
|
|
132
|
-
extends: [plugin.configs.react], // throws if eslint-plugin-react isn't installed
|
|
133
|
-
},
|
|
134
|
-
);
|
|
135
|
-
```
|
|
145
|
+
| Feature | Default | Control it with |
|
|
146
|
+
| --- | --- | --- |
|
|
147
|
+
| [React & Next.js linting](#optional-react-and-nextjs-support) | Auto-detected: on if the relevant peer package is installed | `exadevConfig({ react, nextjs })` |
|
|
148
|
+
| [Gitignore-derived ignores](#gitignore-derived-ignores) | On if the project has a `.gitignore` | `exadevConfig({ gitignore })` |
|
|
149
|
+
| [RFC 8785 canonical JSON formatting](#rfc-8785-canonical-json-formatting) | Always on | Not optional |
|
|
150
|
+
| [package.json key ordering](#optional-packagejson-key-ordering) | On, unless the project already has a syncpack config | `exadevConfig({ packageJsonKeyOrder })` |
|
|
136
151
|
|
|
137
|
-
|
|
152
|
+
Every tri-state option above (`true`/`false`/`undefined`) is passed through the named `exadevConfig(options, ...userConfigs)` factory export:
|
|
138
153
|
|
|
139
154
|
```ts
|
|
140
155
|
// eslint.config.ts
|
|
@@ -152,15 +167,49 @@ export default tseslint.config(
|
|
|
152
167
|
);
|
|
153
168
|
```
|
|
154
169
|
|
|
170
|
+
Trailing arguments are arbitrary flat-config objects, appended in order after everything else — `exadevConfig({}, { rules: { 'no-console': 'warn' } })` is equivalent to spreading the default export plus one more config object. `import exadev from '@exadev/eslint-config'` (the default export) is just `exadevConfig()` called with no arguments.
|
|
171
|
+
|
|
172
|
+
### Optional React and Next.js support
|
|
173
|
+
|
|
174
|
+
React/hooks/a11y and Next.js rule blocks fold in automatically, with no separate import or config needed, gated on two independent, always-both-required conditions:
|
|
175
|
+
|
|
176
|
+
1. **The corresponding package must actually be resolvable.** `eslint-plugin-react`, `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`, and `@next/eslint-plugin-next` are all *optional* peer dependencies (`peerDependenciesMeta.<pkg>.optional: true`) — install only whichever your project actually needs:
|
|
177
|
+
```sh
|
|
178
|
+
pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y # React support
|
|
179
|
+
pnpm add -D @next/eslint-plugin-next # Next.js support
|
|
180
|
+
```
|
|
181
|
+
If none of these resolve, `@exadev/eslint-config`'s default export is byte-for-byte identical to the plain TypeScript ruleset — nothing about the base package changes.
|
|
182
|
+
2. **For React specifically, the file must actually be `.jsx`/`.tsx`.** The React/hooks/a11y rule block is scoped to `files: ['**/*.jsx', '**/*.tsx']`, so even if `eslint-plugin-react` is resolvable only incidentally (e.g. hoisted as a transitive dependency of something unrelated in a monorepo, with zero real JSX anywhere in the linted project), its rules never match a file that isn't JSX. `@next/eslint-plugin-next`'s block carries no such glob: its own presence is already an unambiguous signal (nothing installs it except a real Next.js project).
|
|
183
|
+
|
|
184
|
+
React support pairs `eslint-plugin-react`'s `flat/recommended` with its own `flat/jsx-runtime` config, turning `react/react-in-jsx-scope` and `react/jsx-uses-react` back off. `flat/recommended` alone assumes the classic runtime, where every file using JSX needs `import React` in scope; the automatic JSX runtime (the default since React 17, and the only mode Next.js's own compiler supports) needs no such import. Without this pairing, a consumer on the automatic runtime would see `react/react-in-jsx-scope` fire on every JSX file.
|
|
185
|
+
|
|
186
|
+
**Explicit control**, for anyone who doesn't want to rely on auto-detection:
|
|
187
|
+
|
|
188
|
+
- **`plugin.configs.react`/`plugin.configs.nextjs`** — explicit tier selection, mirroring `plugin.configs.recommended`/`.barrel`. Unlike those two, selecting `.react`/`.nextjs` is itself an explicit request: it **throws** a clear, actionable error if the underlying peer isn't installed, rather than silently returning nothing.
|
|
189
|
+
```ts
|
|
190
|
+
import { plugin } from '@exadev/eslint-config';
|
|
191
|
+
import tseslint from 'typescript-eslint';
|
|
192
|
+
|
|
193
|
+
export default tseslint.config(
|
|
194
|
+
// ...your own config...
|
|
195
|
+
{
|
|
196
|
+
files: ['**/*.tsx'],
|
|
197
|
+
plugins: { exadev: plugin },
|
|
198
|
+
extends: [plugin.configs.react], // throws if eslint-plugin-react isn't installed
|
|
199
|
+
},
|
|
200
|
+
);
|
|
201
|
+
```
|
|
202
|
+
- **`exadevConfig({ react, nextjs })`** — see the tri-state table below.
|
|
203
|
+
|
|
155
204
|
| Value | React (`options.react`) | Next.js (`options.nextjs`) |
|
|
156
205
|
| --- | --- | --- |
|
|
157
206
|
| `true` | Force on — throws if `eslint-plugin-react` isn't resolvable | Force on — throws if `@next/eslint-plugin-next` isn't resolvable |
|
|
158
207
|
| `false` | Force off — always `[]`, no resolution attempted | Force off — always `[]`, no resolution attempted |
|
|
159
208
|
| `undefined` / omitted | Auto-detect (the default) | Auto-detect (the default) |
|
|
160
209
|
|
|
161
|
-
|
|
210
|
+
**Compatibility note:** a consumer who already has `eslint-plugin-react`/`@next/eslint-plugin-next` resolvable for unrelated reasons (e.g. hoisted in a monorepo) and writes `.jsx`/`.tsx` files may see new rule activity the moment they upgrade to a version of this package that ships React/Next.js support, with zero action on their part. This is the normal, widely-accepted ESLint-ecosystem convention that adding rules to a shared/recommended config is a minor bump even though it can newly trip an existing `--max-warnings 0` gate — not a breaking change. Use the `react`/`nextjs` options above to force it off explicitly if needed.
|
|
162
211
|
|
|
163
|
-
|
|
212
|
+
### Gitignore-derived ignores
|
|
164
213
|
|
|
165
214
|
`exadevConfig()`'s default output includes an `ignores` block derived directly from your project's own `.gitignore` (via [`@eslint/config-helpers`](https://www.npmjs.com/package/@eslint/config-helpers)'s `includeIgnoreFile`), so a generated directory your `.gitignore` already knows about (`dist/`, `coverage/`, a tool's own report output) is never linted, without hand-duplicating that list in `eslint.config.ts` too. This closes a real gap: a `.gitignore`d directory that nothing previously linted broadly enough to reach could still get linted the moment a wide-reaching rule (this package's own bundled RFC 8785 JSON canonicalization, say) started matching every file its glob covers.
|
|
166
215
|
|
|
@@ -172,7 +221,7 @@ Trailing arguments are arbitrary flat-config objects, appended in order after ev
|
|
|
172
221
|
|
|
173
222
|
Needs no peer to install — `@eslint/config-helpers` is bundled into this package's own build.
|
|
174
223
|
|
|
175
|
-
|
|
224
|
+
### RFC 8785 canonical JSON formatting
|
|
176
225
|
|
|
177
226
|
Every JSON file is linted against [`eslint-plugin-json-canonical`](https://github.com/ExaDev/eslint-plugin-json-canonical) v2 — plain UTF-16 code-unit key ordering, canonical number formatting, canonical string escaping, and (as of that plugin's own v2) pretty-printed layout (2-space indentation, one member/element per line, a trailing newline), per [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785). This is bundled unconditionally, the same way jsdoc/tsdoc support is: `eslint-plugin-json-canonical` is a plain dependency of this package, so every consumer already has it. There is no option to turn it off.
|
|
178
227
|
|
|
@@ -182,7 +231,7 @@ The plugin's own full-canonicalization rule (`no-insignificant-whitespace`, whic
|
|
|
182
231
|
|
|
183
232
|
`**/package.json` gets everything the plain-JSON config gives every other file — including pretty-printed layout — except `json/sort-keys`, turned back off in its own override block, since its key order is the separate, syncpack-aware concern the next section covers.
|
|
184
233
|
|
|
185
|
-
|
|
234
|
+
### Optional package.json key ordering
|
|
186
235
|
|
|
187
236
|
`exadevConfig({ packageJsonKeyOrder: true })` enables `exadev/package-json-key-order` for `**/package.json`, requiring the same key order [`syncpack format`](https://syncpack.dev/command/format) would produce — `sortFirst` fields (`name`, `description`, `version`, `author` by default) pinned to the top in that exact order, then every other top-level key alphabetically; and, inside each `sortAz`-listed field's own object or array value (`dependencies`, `devDependencies`, `scripts`, `keywords`, and the rest of syncpack's own default list), its members/elements sorted the same way. Confirmed directly against real `syncpack@15` output, not assumed from its docs — see this rule's own source comment for the exact reverse-engineering method (a symbol-before-digit-before-letter, case-insensitive comparison syncpack's docs don't specify precisely enough to derive from prose alone).
|
|
188
237
|
|
|
@@ -196,7 +245,7 @@ This exists for a project that wants real `package.json` canonicalization withou
|
|
|
196
245
|
|
|
197
246
|
Like React/Next.js support, this needs its own optional peer resolvable — `pnpm add -D @eslint/json` — and, unlike them, also needs its `json/json` language registered for the file (this option's own config block does that for you; nothing extra to wire up).
|
|
198
247
|
|
|
199
|
-
Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-detection is
|
|
248
|
+
Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-detection is — `packageJsonKeyOrder: true`/`false` only forces the tri-state explicitly, it isn't the only way to reach it. Not part of `plugin.configs.recommended`, and not available as a `plugin.configs.packageJsonKeyOrder` explicit-tier config the way `.react`/`.nextjs` are, since wiring it through `plugin.configs` would need `plugin.ts` and this option's own config builder to import each other.
|
|
200
249
|
|
|
201
250
|
## Rules
|
|
202
251
|
|
|
@@ -220,7 +269,7 @@ Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-d
|
|
|
220
269
|
| `no-enum-number-widening` | | A bare (non-literal) `number` is accepted anywhere a numeric enum is expected, without checking it is actually one of the enum's members — only a numeric *literal* gets range-checked by `tsc`. No autofix: the only provably safe fix is a genuine runtime membership check against the enum's own values, which is a behavioural choice a mechanical fix cannot responsibly make. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`. |
|
|
221
270
|
| `no-enum-reverse-lookup-widening` | suggestion | Indexing a numeric enum's reverse mapping (`Direction[n]`) with a bare (non-literal) `number`, or with a different enum's member, types as plain `string` for any index, including one outside the enum's actual members, where it genuinely returns `undefined` at runtime — `tsc` does not range-check even a numeric literal index here. When the indexed expression is the init of a variable with an explicit `: string` annotation, a suggestion widens it to `: string \| undefined`, forcing later uses as a bare `string` to surface as real compile errors; every other syntactic position gets a plain report with no fix, and no case gets a full `--fix` autofix. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`. |
|
|
222
271
|
| `prefer-numeric-sort-compare` | suggestion | A deliberately narrow addition alongside `@typescript-eslint/require-array-sort-compare` (which already flags any bare `.sort()`/`.toSorted()` except on a plain string array, with no fix): when the array's element type is definitively `number`, a suggestion offers an ascending compare function (`(a, b) => a - b`), since the default comparator sorts lexicographically (`[1, 2, 10].sort()` becomes `[1, 10, 2]`). Not a full autofix — descending order is a real, if less common, alternative intent. Requires type information — only in the default (type-checked) export, not `plugin.configs.recommended`, since it needs the checker to confirm the array's element type. |
|
|
223
|
-
| `package-json-key-order` | ✓ | Requires `package.json`'s keys to be ordered the same way `syncpack format` would order them. See [Optional package.json key ordering](#optional-
|
|
272
|
+
| `package-json-key-order` | ✓ | Requires `package.json`'s keys to be ordered the same way `syncpack format` would order them. See [Optional package.json key ordering](#optional-packagejson-key-ordering) — opt-in via `exadevConfig({ packageJsonKeyOrder: true })`, not part of `recommended`/`barrel`. A JSON-language rule (`@eslint/json`'s `json/json`), not a TSESLint one — needs no type information and doesn't apply to any `.ts`/`.js` file. |
|
|
224
273
|
| `test-file-kind` | | Requires a test/spec file's own name to declare its test kind via a filename suffix immediately before `.test`/`.spec` (e.g. `foo.unit.test.ts`), one of a configurable `{ kinds }` set (default: `unit`, `integration`, `e2e`). A naming-discipline rule, not a content classifier — it checks only the filename, never what the file actually tests. Self-scoped to real test/spec files (`context.filename`), so it never misfires when applied unscoped and never relies on a consumer's own `files` config. Requires no type information. |
|
|
225
274
|
|
|
226
275
|
## Barrel policy
|
|
@@ -234,11 +283,20 @@ Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-d
|
|
|
234
283
|
| `'single'` (`plugin.configs.barrel`'s explicit choice) | exactly `src/index.ts` | only re-exports | anywhere |
|
|
235
284
|
| `'siblings'` | any `index.ts` | only re-exports | a direct sibling only (`./module`) |
|
|
236
285
|
|
|
237
|
-
`'auto'
|
|
286
|
+
Notes on `'auto'`:
|
|
287
|
+
|
|
288
|
+
- It only ever resolves to `banned` or `single` — there's no single-signal auto-equivalent for `siblings` (which package.json field would suggest "any index file, not just the entry point"?), so a project wanting that policy states it explicitly, e.g. to permit any index file as a barrel rather than just `src/index.ts` (flat-config later blocks override earlier rule settings):
|
|
289
|
+
```ts
|
|
290
|
+
...exadev,
|
|
291
|
+
{ rules: { 'exadev/barrel-policy': ['error', { mode: 'siblings' }] } }, // any index file may be a barrel, not just src/index.ts
|
|
292
|
+
```
|
|
293
|
+
- `private: true` in `package.json` is not consulted by the detection: a pnpm workspace package is routinely both `private` and a genuine import target for sibling packages via `exports`, so `private` says nothing about whether a barrel is warranted.
|
|
238
294
|
|
|
239
|
-
In every mode, re-exports are banned outside a permitted barrel, and a permitted barrel may contain only re-export statements. The umbrella composes the identical predicates the standalone rules use (shared in `src/rules/barrel-helpers.ts`). It is non-fixable — the autofix lives on `no-non-barrel-reexport`.
|
|
295
|
+
In every mode, re-exports are banned outside a permitted barrel, and a permitted barrel may contain only re-export statements. The umbrella composes the identical predicates the standalone rules use (shared in [`src/rules/barrel-helpers.ts`](src/rules/barrel-helpers.ts)). It is non-fixable — the autofix lives on `no-non-barrel-reexport`.
|
|
240
296
|
|
|
241
|
-
##
|
|
297
|
+
## Development
|
|
298
|
+
|
|
299
|
+
### Build, test, and lint
|
|
242
300
|
|
|
243
301
|
```sh
|
|
244
302
|
pnpm install # requires Node >=20 and pnpm 11.6.0 (pinned via packageManager)
|
|
@@ -248,53 +306,46 @@ pnpm test
|
|
|
248
306
|
pnpm build
|
|
249
307
|
```
|
|
250
308
|
|
|
251
|
-
Each rule has a co-located `*.unit.test.ts` exercising it with ESLint's `RuleTester` under Vitest. `vitest.setup.ts` wires `RuleTester.describe`/`.it`/`.itOnly` to Vitest's `describe`/`it` explicitly (no `test.globals`). Each test uses typescript-eslint's parser for TypeScript-only fixtures; none need type information.
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
`pnpm
|
|
256
|
-
|
|
257
|
-
The `lint`/`typecheck`/`test`/`build` npm scripts wrap turbo tasks named `_lint`/`_typecheck`/`_test`/`_build` — run `pnpm build`, not `turbo run build`.
|
|
258
|
-
|
|
259
|
-
`pnpm build` runs `tsdown` from `src/index.ts`, bundling the whole module graph into ESM + CJS + declarations. `prepublishOnly` re-runs lint, typecheck, `test`, `tsdown`, `publint`, and `attw --pack`.
|
|
260
|
-
|
|
261
|
-
## Architecture
|
|
262
|
-
|
|
263
|
-
`src/plugin.ts` builds a `TSESLint.FlatConfig.Plugin` (`@typescript-eslint/utils`'s own type — not ESLint's own `ESLint.Plugin`, which can't hold a rule built with `ESLintUtils.RuleCreator`) combining `src/rules/` into a flat `rules` map. `configs.recommended`, `.barrel`, `.react`, and `.nextjs` are getters in the object literal — each references the fully-built `plugin` (`plugins: { exadev: plugin }`), which a plain property initializer can't do mid-construction. `recommended` ships `barrel-policy` at `mode: 'banned'`; `barrel` at `mode: 'single'`; `.react`/`.nextjs` call `buildReactConfig`/`buildNextjsConfig` with `enabled: true` (see below).
|
|
264
|
-
|
|
265
|
-
`src/config-types.ts` holds `ConfigValue`/`ConfigArrayValue` (`ConfigArrayValue = Extract<ConfigValue, unknown[]>`, the array-only member of ESLint's own config-value union), shared by every file below rather than redefined per file — annotating a config array with the wider `ConfigValue` union directly broke `...exadev` with `TS2488` ("must have a Symbol.iterator method").
|
|
266
|
-
|
|
267
|
-
`src/optional-plugin.ts` is the lazy-resolution helper behind React/Next.js support: `tryRequire` wraps `createRequire(import.meta.url)` in try/catch, returning `unknown` (never a cast) so every call site narrows explicitly before use; `readFlatConfig` walks a property path through that `unknown` value via a real type guard, normalizing a stray legacy top-level `parserOptions` key into `languageOptions.parserOptions` along the way (confirmed necessary: `eslint-plugin-jsx-a11y`'s own `configs.recommended` export carries exactly this legacy shape, which flat config's schema rejects outright rather than ignores).
|
|
268
|
-
|
|
269
|
-
`src/react.ts`/`src/nextjs.ts` each export a `build*Config(options)` function: resolve the relevant optional peer(s) via `tryRequire`, extract their real flat config via `readFlatConfig`, and return an array of 0-or-more config blocks — `[]` if unresolvable and not explicitly forced on, a thrown `Error` if explicitly forced on (`enabled: true`) and still unresolvable. `react.ts`'s blocks are scoped to `files: ['**/*.jsx', '**/*.tsx']`; `nextjs.ts`'s is not (see [Optional React and Next.js support](#optional-react-and-nextjs-support) for why).
|
|
270
|
-
|
|
271
|
-
`src/create-config.ts` is config assembly's single source of truth: `exadevConfig(options, ...userConfigs)` concatenates `recommendedTypeChecked` with both builders' output (each fed the matching tri-state option) and any trailing user configs; `defaultConfig` is `exadevConfig()` evaluated once, eagerly, at module load.
|
|
309
|
+
- Each rule has a co-located `*.unit.test.ts` exercising it with ESLint's `RuleTester` under Vitest. [`vitest.setup.ts`](vitest.setup.ts) wires `RuleTester.describe`/`.it`/`.itOnly` to Vitest's `describe`/`it` explicitly (no `test.globals`). Each test uses typescript-eslint's parser for TypeScript-only fixtures; none need type information.
|
|
310
|
+
- Every test file's own name declares its kind via a filename suffix immediately before `.test`/`.spec` — `.unit`, `.integration`, or `.e2e` by default (`exadev/test-file-kind`, part of `recommended`; see [Rules](#rules)) — so a file's test kind is always visible from its name alone, without opening it, and downstream tooling (e.g. a Vitest project split by test kind) can select by filename glob rather than by convention nobody enforces. This package's own tests are exclusively `.unit.test.ts` today (a `.internal.unit.test.ts` variant exists for a handful of files that also test non-exported internals directly, `internal` just being an ordinary extra name segment — see [`no-mutable-union-array-param.internal.unit.test.ts`](src/rules/no-mutable-union-array-param.internal.unit.test.ts)).
|
|
311
|
+
- `pnpm test` always measures coverage (`@vitest/coverage-v8`), scoped to `src/**/*.ts` excluding `*.test.ts`. Text output in terminal; `html`/`lcov` in `coverage/` (gitignored alongside `.eslintcache` and `dist/`).
|
|
312
|
+
- The `lint`/`typecheck`/`test`/`build` npm scripts wrap turbo tasks named `_lint`/`_typecheck`/`_test`/`_build` — run `pnpm build`, not `turbo run build`.
|
|
313
|
+
- `pnpm build` runs `tsdown` from [`src/index.ts`](src/index.ts), bundling the whole module graph into ESM + CJS + declarations. `prepublishOnly` re-runs lint, typecheck, `test`, `tsdown`, `publint`, and `attw --pack`.
|
|
272
314
|
|
|
273
|
-
|
|
315
|
+
### Architecture
|
|
274
316
|
|
|
275
|
-
|
|
317
|
+
<details>
|
|
318
|
+
<summary>Expand for implementation internals (not needed for ordinary consumption)</summary>
|
|
276
319
|
|
|
277
|
-
|
|
320
|
+
- [`src/plugin.ts`](src/plugin.ts) builds a `TSESLint.FlatConfig.Plugin` (`@typescript-eslint/utils`'s own type — not ESLint's own `ESLint.Plugin`, which can't hold a rule built with `ESLintUtils.RuleCreator`) combining [`src/rules/`](src/rules) into a flat `rules` map. `configs.recommended`, `.barrel`, `.react`, and `.nextjs` are getters in the object literal — each references the fully-built `plugin` (`plugins: { exadev: plugin }`), which a plain property initializer can't do mid-construction. `recommended` ships `barrel-policy` at `mode: 'banned'`; `barrel` at `mode: 'single'`; `.react`/`.nextjs` call `buildReactConfig`/`buildNextjsConfig` with `enabled: true` (see below).
|
|
321
|
+
- [`src/config-types.ts`](src/config-types.ts) holds `ConfigValue`/`ConfigArrayValue` (`ConfigArrayValue = Extract<ConfigValue, unknown[]>`, the array-only member of ESLint's own config-value union), shared by every file below rather than redefined per file — annotating a config array with the wider `ConfigValue` union directly broke `...exadev` with `TS2488` ("must have a Symbol.iterator method").
|
|
322
|
+
- [`src/optional-plugin.ts`](src/optional-plugin.ts) is the lazy-resolution helper behind React/Next.js support: `tryRequire` wraps `createRequire(import.meta.url)` in try/catch, returning `unknown` (never a cast) so every call site narrows explicitly before use; `readFlatConfig` walks a property path through that `unknown` value via a real type guard, normalizing a stray legacy top-level `parserOptions` key into `languageOptions.parserOptions` along the way (confirmed necessary: `eslint-plugin-jsx-a11y`'s own `configs.recommended` export carries exactly this legacy shape, which flat config's schema rejects outright rather than ignores).
|
|
323
|
+
- [`src/react.ts`](src/react.ts)/[`src/nextjs.ts`](src/nextjs.ts) each export a `build*Config(options)` function: resolve the relevant optional peer(s) via `tryRequire`, extract their real flat config via `readFlatConfig`, and return an array of 0-or-more config blocks — `[]` if unresolvable and not explicitly forced on, a thrown `Error` if explicitly forced on (`enabled: true`) and still unresolvable. `react.ts`'s blocks are scoped to `files: ['**/*.jsx', '**/*.tsx']`; `nextjs.ts`'s is not (see [Optional React and Next.js support](#optional-react-and-nextjs-support) for why).
|
|
324
|
+
- [`src/create-config.ts`](src/create-config.ts) is config assembly's single source of truth: `exadevConfig(options, ...userConfigs)` concatenates `recommendedTypeChecked` with both builders' output (each fed the matching tri-state option) and any trailing user configs; `defaultConfig` is `exadevConfig()` evaluated once, eagerly, at module load.
|
|
325
|
+
- [`src/index.ts`](src/index.ts) is the entry point, still a pure re-export barrel (required by `no-side-effects-in-index`/`no-non-barrel-reexport`, both of which assume this file contains nothing but `export ... from ...`): `export { defaultConfig as default, exadevConfig } from './create-config'; export { default as plugin } from './plugin';`. All exports share one root module, so importing `{ plugin }` alone still resolves `typescript-eslint` via the sibling re-export — an accepted trade-off (an earlier separate-subpath split proved more awkward in practice). React/Next.js support never adds to this cost: none of the four optional packages are ever statically imported, only passed as a runtime string to `createRequire`'s resolver, so their absence never affects module evaluation for a consumer who doesn't use them.
|
|
326
|
+
- [`pnpm-workspace.yaml`](pnpm-workspace.yaml) declares an empty `packages: []` — not a real workspace, just giving turbo a root for local task caching.
|
|
278
327
|
|
|
279
|
-
|
|
328
|
+
</details>
|
|
280
329
|
|
|
281
|
-
|
|
330
|
+
### Conventions
|
|
282
331
|
|
|
283
|
-
|
|
332
|
+
- [`eslint.config.ts`](eslint.config.ts) dogfoods this package's own factory export on itself (`import { exadevConfig } from './src/index'`), spreading `exadevConfig({ react: false, nextjs: false })` — forced off explicitly, not the plain auto-detecting default, since `eslint-plugin-react`/`@next/eslint-plugin-next` are real devDependencies of *this* repo (needed to test [`src/react.ts`](src/react.ts)/[`src/nextjs.ts`](src/nextjs.ts)'s own "package is resolvable" branch) even though this repo is neither a React nor a Next.js project. `no-side-effects-in-index` and `no-non-barrel-reexport` self-scope to [`src/index.ts`](src/index.ts) internally, so no `files`/`ignores` wiring is needed here. Plugin construction lives in [`src/plugin.ts`](src/plugin.ts) specifically so `src/index.ts` stays a pure re-export point.
|
|
333
|
+
- [`tsconfig.json`](tsconfig.json) enables `verbatimModuleSyntax` (`import type`/`export type` required for type-only imports — also enforced by `consistent-type-imports`) and `noUncheckedIndexedAccess` (narrow indexed access before use rather than asserting).
|
|
334
|
+
- Conventional commits are enforced by commitlint, restricted to the type-enum defined once in [`release.config.ts`](release.config.ts)'s `commitTypes` — both commitlint and semantic-release derive from that single list.
|
|
284
335
|
|
|
285
|
-
|
|
336
|
+
### Gotchas and quirks
|
|
286
337
|
|
|
287
|
-
- `.attw.json` ignores `false-export-default`: tsdown/rolldown's CJS output for this plugin's sole default export doesn't emit the `export =` form `arethetypeswrong` wants under legacy `node10` resolution. The modes ESLint flat config uses (`node16`, `bundler`) are unaffected, so the rule is suppressed rather than changing the default-export shape.
|
|
288
|
-
- `src/index.ts` mixing a default export with a named one triggers rolldown's `MIXED_EXPORTS` warning: a raw CommonJS `require()` would see the raw exports object instead of the default. ESM `import` (the actual consumer path) resolves both correctly; `attw --pack` and `publint` report no problems, so the warning is accepted (see `tsdown.config.ts`).
|
|
338
|
+
- [`.attw.json`](.attw.json) ignores `false-export-default`: tsdown/rolldown's CJS output for this plugin's sole default export doesn't emit the `export =` form `arethetypeswrong` wants under legacy `node10` resolution. The modes ESLint flat config uses (`node16`, `bundler`) are unaffected, so the rule is suppressed rather than changing the default-export shape.
|
|
339
|
+
- [`src/index.ts`](src/index.ts) mixing a default export with a named one triggers rolldown's `MIXED_EXPORTS` warning: a raw CommonJS `require()` would see the raw exports object instead of the default. ESM `import` (the actual consumer path) resolves both correctly; `attw --pack` and `publint` report no problems, so the warning is accepted (see [`tsdown.config.ts`](tsdown.config.ts)).
|
|
289
340
|
- Husky hooks: `pre-commit` runs lint-staged (`eslint --fix` on staged `*.ts`), `commit-msg` runs commitlint, `pre-push` runs typecheck + test + build.
|
|
290
341
|
- The CI release job sets `HUSKY=0` (commit-msg hook skips the automated release commit) and blanks `NPM_TOKEN`/`NODE_AUTH_TOKEN` explicitly so an inherited token can't win over OIDC trusted publishing.
|
|
291
|
-
- A consumer who already has `eslint-plugin-react`/`@next/eslint-plugin-next` resolvable for unrelated reasons (e.g. hoisted in a monorepo) and writes `.jsx`/`.tsx` files may see new rule activity the moment they upgrade to a version of this package that ships React/Next.js support — with zero action on their part.
|
|
342
|
+
- A consumer who already has `eslint-plugin-react`/`@next/eslint-plugin-next` resolvable for unrelated reasons (e.g. hoisted in a monorepo) and writes `.jsx`/`.tsx` files may see new rule activity the moment they upgrade to a version of this package that ships React/Next.js support — with zero action on their part. See the compatibility note under [Optional React and Next.js support](#optional-react-and-nextjs-support).
|
|
292
343
|
|
|
293
|
-
|
|
344
|
+
### Contributing
|
|
294
345
|
|
|
295
346
|
Conventional commits are enforced by a husky `commit-msg` hook and re-checked in CI. CI runs commitlint, lint, and typecheck+test+build+attw on every push and pull request; the release job runs only on push to `main`, after all pass.
|
|
296
347
|
|
|
297
|
-
|
|
348
|
+
### Release
|
|
298
349
|
|
|
299
350
|
Conventional commits drive [semantic-release](https://semantic-release.gitbook.io/semantic-release) on every push to `main`: version bump, `CHANGELOG.md`, GitHub Release, and npm publish via OIDC (no stored token). A second CI job republishes the identical build under the unscoped alias `exadev-eslint-config`.
|
|
300
351
|
|
package/dist/index.cjs
CHANGED
package/dist/index.js
CHANGED
package/package.json
CHANGED