@kirill.konshin/lint 0.7.3 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +160 -113
- package/dist/config.d.ts +103 -0
- package/dist/config.js +112 -0
- package/dist/configs/base.d.ts +1 -1
- package/dist/configs/nx.d.ts +1 -1
- package/dist/configs/nx.js +3 -8
- package/dist/configs/react.d.ts +3 -3
- package/dist/configs/react.js +6 -16
- package/dist/configs/storybook.d.ts +3 -3
- package/dist/configs/storybook.js +4 -9
- package/dist/configs/tailwind.d.ts +6 -25
- package/dist/configs/tailwind.js +3 -64
- package/dist/configs/testing.d.ts +1 -1
- package/dist/configs/testing.js +3 -15
- package/dist/configs/turbo.d.ts +2 -2
- package/dist/configs/turbo.js +4 -6
- package/dist/configs/typescriptTypeAware.d.ts +1 -1
- package/dist/gates.d.ts +72 -0
- package/dist/gates.js +132 -0
- package/dist/index.d.ts +15 -51
- package/dist/index.js +16 -14
- package/dist/lib.d.ts +1 -1
- package/dist/lib.js +1 -1
- package/dist/lintPrepare.d.ts +75 -28
- package/dist/lintPrepare.js +243 -35
- package/dist/testColocation.js +1 -1
- package/dist/vitePlus.d.ts +8 -18
- package/dist/vitePlus.js +40 -47
- package/package.json +7 -4
- package/rules/agent.md +1 -0
- package/rules/auth.md +3 -3
- package/rules/db.md +6 -9
- package/rules/expo.md +2 -0
- package/rules/github.md +1 -1
- package/rules/gitlab.md +1 -1
- package/rules/i18n.md +3 -0
- package/rules/monorepo-turbo-nx.md +38 -4
- package/rules/mui.md +8 -18
- package/rules/nextjs.md +13 -13
- package/rules/npm-yarn.md +28 -118
- package/rules/nx.md +1 -1
- package/rules/playwright.md +1 -1
- package/rules/react.md +7 -32
- package/rules/tailwind.md +9 -47
- package/rules/testing.md +2 -2
- package/rules/turbo.md +1 -1
- package/rules/typescript.md +6 -2
- package/rules/ui-kit.md +6 -0
- package/rules/vite.md +1 -1
- package/skills/lint-db/SKILL.md +23 -0
- package/skills/lint-electron/SKILL.md +9 -6
- package/skills/lint-github/SKILL.md +15 -8
- package/skills/lint-gitlab/SKILL.md +20 -5
- package/skills/lint-migrate/SKILL.md +18 -2
- package/skills/lint-mui/SKILL.md +28 -0
- package/skills/lint-nextjs/SKILL.md +53 -16
- package/skills/lint-npm-yarn/SKILL.md +126 -0
- package/skills/lint-repo/SKILL.md +12 -12
- package/skills/lint-tailwind/SKILL.md +53 -0
- package/skills/lint-webstorm/SKILL.md +3 -3
- package/skills/lint-worktree/SKILL.md +25 -9
- package/skills/spec-author/SKILL.md +2 -2
- package/skills/spec-steward/SKILL.md +1 -1
- package/skills/spec-steward/references/apply.md +1 -1
- package/skills/spec-steward/references/contract.md +2 -2
- package/skills/spec-steward/references/model.md +2 -2
- package/skills/spec-steward/references/review-format.md +4 -4
- package/skills/spec-steward/references/wiring.md +2 -2
- package/skills/spec-steward/references/worker.md +1 -1
- package/skills/spec-tools/SKILL.md +2 -2
- package/skills/spec-tools/references/rules/common.md +1 -1
- package/skills/spec-tools/references/rules/spec-steward.md +1 -1
- package/skills/spec-tools/scripts/cli.js +2 -2
- package/skills/spec-verify/SKILL.md +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[Vite+](https://viteplus.dev) configuration (Oxlint, Oxfmt, staged checks) — or ESLint + Prettier + lint-staged + Husky without Vite+ — plus AI agent rules & skills for monorepos, in one package.
|
|
4
4
|
|
|
5
|
-
Upgrading from an older version: use the `lint-migrate` skill (shipped in `skills/`,
|
|
5
|
+
Upgrading from an older version: use the `lint-migrate` skill (shipped in `skills/`, installed by `lint-prepare`).
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
@@ -12,7 +12,7 @@ Recommended, with [Vite+](#vite-recommended):
|
|
|
12
12
|
$ yarn add -D vite-plus @kirill.konshin/lint @yarnpkg/types
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
Without Vite+, see [ESLint + Prettier](#eslint--prettier-without-vite).
|
|
15
|
+
Without Vite+, see [ESLint + Prettier](#eslint--prettier-without-vite). `vite-plus` is a required peer either way: the `vitePlus` key of `lint.config.ts` is typed with its config.
|
|
16
16
|
|
|
17
17
|
Every project whose `packageManager` is Yarn must directly install `@yarnpkg/types`; Yarn PnP does not allow `yarn.config.cjs` to require a transitive dependency (Vite+ does not support PnP anyway).
|
|
18
18
|
|
|
@@ -86,29 +86,90 @@ yarn-error*
|
|
|
86
86
|
|
|
87
87
|
List need to be verified, especially `build`, `coverage`, `dist` must be verified not to exclude legit folders. With Vite+ add `.vite-hooks/_` (the generated hook dispatcher).
|
|
88
88
|
|
|
89
|
+
## `lint.config.ts`
|
|
90
|
+
|
|
91
|
+
Every project that installs this package has one `lint.config.ts`, in the workspace root (a monorepo has exactly one; packages are never searched). Every entry point reads it: `vitePlusConfig`, `eslintConfig` and `lint-prepare` (which warns while it is missing; the defaults apply until then). Write it by hand (or let an agent write it per the `lint-repo` skill); no tool generates it. The smallest one:
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import { defineLintConfig } from '@kirill.konshin/lint/config';
|
|
95
|
+
|
|
96
|
+
export default defineLintConfig({});
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Import from `@kirill.konshin/lint/config` — it loads no ESLint plugin. Node loads the file natively (type stripping, Node ≥ 22.18), so use erasable TypeScript only, and set `"type": "module"` in the root `package.json` (otherwise Node warns on every load).
|
|
100
|
+
|
|
101
|
+
Toggle notation, the same for every key:
|
|
102
|
+
|
|
103
|
+
- `undefined` (default) — auto-detect, see [Detection](#detection)
|
|
104
|
+
- `true` — force ON (use when detection misses a tool, can be useful to see the error why tool is missing)
|
|
105
|
+
- `false` — force OFF, same as `{ enabled: false }`
|
|
106
|
+
- `{ /* options */ }` — implies `enabled: true` even if omitted; `enabled: false` turns OFF keeping the other options
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
import { defineLintConfig, tsExts } from '@kirill.konshin/lint/config'; // tsExts, scanWorkspace: for globs and file lists
|
|
110
|
+
|
|
111
|
+
export default defineLintConfig({
|
|
112
|
+
// enabled (default true) = tools are ON unless said otherwise;
|
|
113
|
+
// strict (default false) = same-scope package probes only, no workspace evidence scans
|
|
114
|
+
detection: { enabled: true, strict: false }, // default
|
|
115
|
+
|
|
116
|
+
// ON by default; app roots auto-detected (next.config.*, package.json depending on next, src/{app,pages}/);
|
|
117
|
+
// several apps auto-detect as array; pass the package root, not src
|
|
118
|
+
next: { rootDir: 'apps/web' }, // string or array
|
|
119
|
+
|
|
120
|
+
storybook: true, // force ON if detection failed
|
|
121
|
+
turbo: false, // force OFF
|
|
122
|
+
nx: true,
|
|
123
|
+
jest: false,
|
|
124
|
+
vitest: { enabled: true },
|
|
125
|
+
|
|
126
|
+
// ON by default; auto-detected single entry CSS; explicit path always wins over the scan
|
|
127
|
+
tailwind: { cssConfigPath: 'apps/web/src/app/index.css' },
|
|
128
|
+
|
|
129
|
+
// ESLint only
|
|
130
|
+
eslint: {
|
|
131
|
+
defaultIgnore: { importMetaUrl: import.meta.url }, // OFF by default; .gitignore + .prettierignore as ESLint ignores
|
|
132
|
+
typeAware: true, // OFF by default (slow) - see "Type-aware rules"
|
|
133
|
+
},
|
|
134
|
+
|
|
135
|
+
// Vite+ only: settings, plus the project's own Vite+ blocks (merged over the defaults, see "Vite+")
|
|
136
|
+
vitePlus: {
|
|
137
|
+
typeAware: false, // ON by default: `vp check` is the type check
|
|
138
|
+
lint: { rules: {}, overrides: [], ignorePatterns: ['generated'] }, // added to the defaults
|
|
139
|
+
fmt: { ignorePatterns: ['generated'] }, // added to the defaults (.idea, .husky, .yarn, OpenSpec files)
|
|
140
|
+
test: { projects: ['packages/*'] }, // any other Vite+ / Vite block passes through
|
|
141
|
+
},
|
|
142
|
+
|
|
143
|
+
// skills lint-prepare installs, keyed by source, merged over the defaults (see "AI Agent Rules")
|
|
144
|
+
skills: {
|
|
145
|
+
'expo/skills': false, // a default source, turned off
|
|
146
|
+
'vercel-labs/agent-skills': { skills: { 'vercel-react-native-skills': false } }, // a default source, one skill left out
|
|
147
|
+
'mattpocock/skills': { skills: { tdd: true } }, // an extra source, only this skill
|
|
148
|
+
'@kirill.konshin/lint': { skills: { 'lint-electron': false } }, // this package's own skills
|
|
149
|
+
},
|
|
150
|
+
|
|
151
|
+
// package rules by name: false leaves a rule out
|
|
152
|
+
rules: { redux: false },
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Entry points take the same shape as their last argument, merged deep over the file (objects merge, arrays and values are replaced): use it only for per-package differences in a monorepo (e.g. a nested ESLint config).
|
|
157
|
+
|
|
89
158
|
## Vite+ (recommended)
|
|
90
159
|
|
|
91
|
-
`vite.config.ts` at the workspace root
|
|
160
|
+
`vite.config.ts` at the workspace root is always the same — every setting and every project block lives in the `vitePlus` key of [`lint.config.ts`](#lintconfigts):
|
|
92
161
|
|
|
93
162
|
```ts
|
|
94
163
|
import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
|
|
95
164
|
import { defineConfig } from 'vite-plus';
|
|
96
165
|
|
|
97
|
-
export default defineConfig(
|
|
98
|
-
vitePlusConfig(
|
|
99
|
-
{
|
|
100
|
-
lint: { rules: {}, overrides: [] }, // added to the defaults
|
|
101
|
-
fmt: { ignorePatterns: ['generated'] }, // added to the defaults (.idea, .husky, .yarn, OpenSpec files)
|
|
102
|
-
test: { projects: ['packages/*'] }, // any other Vite+ / Vite block passes through
|
|
103
|
-
},
|
|
104
|
-
// same toggles as ESLint's defineLintConfig, see Detection
|
|
105
|
-
{ next: true, tailwind: { cssConfigPath: 'apps/web/src/app.css' }, typeAware: false }, // typeAware is on by default
|
|
106
|
-
),
|
|
107
|
-
);
|
|
166
|
+
export default defineConfig(vitePlusConfig());
|
|
108
167
|
```
|
|
109
168
|
|
|
169
|
+
`vitePlusConfig` returns the `lint` (Oxlint), `fmt` (Oxfmt) and `staged` blocks plus the project blocks as a `Promise`; `defineConfig` from `vite-plus` awaits it. Its optional arguments (`vitePlusConfig(config, overrides)`: Vite+ blocks, then `lint.config.ts` overrides) are for exceptions only.
|
|
170
|
+
|
|
110
171
|
- Merging: lists add up (`plugins`, `jsPlugins`, `overrides`, `ignorePatterns`), maps merge by key (`rules`, `settings`, `env`), a `staged` block replaces the default
|
|
111
|
-
- Building blocks are exported: `lintConfig(
|
|
172
|
+
- Building blocks are exported: `lintConfig(config)` (synchronous, takes a resolved config), `fmtConfig()`, `stagedConfig()`
|
|
112
173
|
- Lint and format settings live in the **root** config only: Vite+ ignores nested `lint`/`fmt` blocks, use `lint.overrides` / `fmt.overrides` with workspace paths
|
|
113
174
|
- `.gitignore` and `.prettierignore` are honoured by Oxfmt; the recommended `.prettierignore` entries are default `fmt.ignorePatterns`, add others there
|
|
114
175
|
|
|
@@ -154,7 +215,7 @@ What maps where:
|
|
|
154
215
|
</tbody>
|
|
155
216
|
</table>
|
|
156
217
|
|
|
157
|
-
Not carried over: `@nx/dependency-checks` (Oxlint does not lint JSON), `@typescript-eslint/naming-convention` (type-aware only, off by default). `@nx/eslint-plugin` needs the `eslint` package installed (as a library; ESLint itself does not run). Oxlint type-aware linting and type checking (tsgolint, the TypeScript 7 engine) are on by default — `vp check` is the type check, `vp pack` does not type-check; `typeAware: false` turns them off. tsgolint rejects tsconfig options TypeScript 7 removed (`target: es5`, `moduleResolution: node`, `downlevelIteration`).
|
|
218
|
+
Not carried over: `@nx/dependency-checks` (Oxlint does not lint JSON), `@typescript-eslint/naming-convention` (type-aware only, off by default). `@nx/eslint-plugin` needs the `eslint` package installed (as a library; ESLint itself does not run). Oxlint type-aware linting and type checking (tsgolint, the TypeScript 7 engine) are on by default — `vp check` is the type check, `vp pack` does not type-check; `vitePlus: { typeAware: false }` turns them off. tsgolint rejects tsconfig options TypeScript 7 removed (`target: es5`, `moduleResolution: node`, `downlevelIteration`).
|
|
158
219
|
|
|
159
220
|
`package.json`:
|
|
160
221
|
|
|
@@ -182,10 +243,38 @@ vp staged
|
|
|
182
243
|
|
|
183
244
|
Library packages build with `vp pack` from a `pack` block (tsdown) in their own `vite.config.ts`, and test with `vp test`; tests import from `vite-plus/test`.
|
|
184
245
|
|
|
185
|
-
##
|
|
246
|
+
## Editor Config `.editorconfig`
|
|
247
|
+
|
|
248
|
+
Oxfmt reads it too; `fmtConfig()` sets the Prettier behaviors that differ from it.
|
|
249
|
+
|
|
250
|
+
```editorconfig
|
|
251
|
+
root = true
|
|
252
|
+
|
|
253
|
+
[*]
|
|
254
|
+
indent_style = space
|
|
255
|
+
end_of_line = lf
|
|
256
|
+
charset = utf-8
|
|
257
|
+
trim_trailing_whitespace = true
|
|
258
|
+
insert_final_newline = false
|
|
259
|
+
max_line_length = 120
|
|
260
|
+
|
|
261
|
+
[*.md]
|
|
262
|
+
max_line_length = 99999
|
|
263
|
+
|
|
264
|
+
[*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}]
|
|
265
|
+
indent_size = 4
|
|
266
|
+
|
|
267
|
+
[*.{css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}]
|
|
268
|
+
indent_size = 2
|
|
269
|
+
|
|
270
|
+
[Makefile]
|
|
271
|
+
indent_style = tab
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
## ESLint + Prettier (without Vite+, legacy, not recommended)
|
|
186
275
|
|
|
187
276
|
```bash
|
|
188
|
-
$ yarn add -D eslint prettier @kirill.konshin/lint @yarnpkg/types husky lint-staged
|
|
277
|
+
$ yarn add -D eslint prettier vite-plus @kirill.konshin/lint @yarnpkg/types husky lint-staged
|
|
189
278
|
```
|
|
190
279
|
|
|
191
280
|
### `.prettierignore`
|
|
@@ -211,28 +300,24 @@ https://prettier.io/docs/ignore:
|
|
|
211
300
|
|
|
212
301
|
`eslint.config.mjs`:
|
|
213
302
|
|
|
214
|
-
Every tool integration — Next.js, Nx, Turborepo, Storybook, Jest, Vitest, Tailwind — is auto-detected (the detection results are exported as `has*` booleans for debugging).
|
|
303
|
+
Every tool integration — Next.js, Nx, Turborepo, Storybook, Jest, Vitest, Tailwind — is auto-detected (the detection results are exported as `has*` booleans for debugging). Settings come from [`lint.config.ts`](#lintconfigts); `eslintConfig(overrides)` merges its argument over them:
|
|
215
304
|
|
|
216
305
|
```js
|
|
217
306
|
import { defineConfig } from 'eslint/config';
|
|
218
|
-
import {
|
|
307
|
+
import { eslintConfig } from '@kirill.konshin/lint';
|
|
219
308
|
|
|
220
|
-
// every tool integration auto-detected
|
|
221
|
-
export default defineConfig(
|
|
222
|
-
await defineLintConfig({
|
|
223
|
-
defaultIgnore: { importMetaUrl: import.meta.url }, // .gitignore + .prettierignore as ESLint ignores
|
|
224
|
-
}),
|
|
225
|
-
);
|
|
309
|
+
// every tool integration auto-detected, settings from lint.config.ts
|
|
310
|
+
export default defineConfig(await eslintConfig());
|
|
226
311
|
```
|
|
227
312
|
|
|
228
|
-
|
|
313
|
+
`eslintConfig` returns a `Promise` (natively awaited by ESLint), to compose with your own blocks, `await` it:
|
|
229
314
|
|
|
230
315
|
```js
|
|
231
316
|
import { defineConfig } from 'eslint/config';
|
|
232
|
-
import {
|
|
317
|
+
import { eslintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
|
|
233
318
|
|
|
234
319
|
export default defineConfig([
|
|
235
|
-
...(await
|
|
320
|
+
...(await eslintConfig({ eslint: { defaultIgnore: { importMetaUrl: import.meta.url } } })),
|
|
236
321
|
{
|
|
237
322
|
name: 'Custom rules',
|
|
238
323
|
rules: {
|
|
@@ -243,53 +328,23 @@ export default defineConfig([
|
|
|
243
328
|
]);
|
|
244
329
|
```
|
|
245
330
|
|
|
246
|
-
####
|
|
331
|
+
#### Type-aware file list
|
|
247
332
|
|
|
248
|
-
|
|
333
|
+
`eslint.typeAware` takes the typescript-eslint project service options:
|
|
249
334
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
- `false` — force OFF
|
|
253
|
-
- `{ /* tool options *./ }` — object configuration implies `enabled: true` even if omitted; set `enabled: false` to force OFF while keeping the other options in place, see example
|
|
254
|
-
|
|
255
|
-
```js
|
|
256
|
-
import { defineConfig } from 'eslint/config';
|
|
257
|
-
import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint';
|
|
258
|
-
|
|
259
|
-
// function form shown
|
|
260
|
-
export default defineConfig(
|
|
261
|
-
await defineLintConfig({
|
|
262
|
-
// enabled (default true) = tools are ON unless said otherwise;
|
|
263
|
-
// strict (default false) = same-scope package probes only, no workspace evidence scans
|
|
264
|
-
// `{ enabled: false, strict: true }` is ideal for per-package configs
|
|
265
|
-
detection: { enabled: true, strict: false }, // default
|
|
266
|
-
|
|
267
|
-
// ON by default; app roots auto-detected (next.config.*, package.json depending on next, src/{app,pages}/);
|
|
268
|
-
// can be force OFF; several apps auto-detect as array; pass the package root, not src
|
|
269
|
-
next: { rootDir: 'apps/web' }, // string or array
|
|
270
|
-
|
|
271
|
-
storybook: true, // force ON if detection failed
|
|
272
|
-
turbo: false, // force OFF
|
|
273
|
-
nx: true,
|
|
274
|
-
jest: false,
|
|
275
|
-
vitest: { enabled: true }, // object form implies ON; { enabled: false, ... } turns OFF keeping options
|
|
276
|
-
|
|
277
|
-
// ON by default; auto-detected single entry CSS; explicit path always wins over the scan
|
|
278
|
-
tailwind: { cssConfigPath: 'apps/web/src/app/index.css' },
|
|
279
|
-
|
|
280
|
-
// OFF by default
|
|
281
|
-
defaultIgnore: {
|
|
282
|
-
importMetaUrl: import.meta.url, // required, error if turned on via `defaultIgnore: true`
|
|
283
|
-
},
|
|
335
|
+
```ts
|
|
336
|
+
import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint/config';
|
|
284
337
|
|
|
338
|
+
export default defineLintConfig({
|
|
339
|
+
eslint: {
|
|
285
340
|
// OFF by default (slow) - see "Type-aware rules"
|
|
286
341
|
typeAware: {
|
|
287
342
|
allowDefaultProject: scanWorkspace('{vite,vitest}.config.ts'), // no default; absolute paths are relativized; ** globs are not supported
|
|
288
343
|
maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50, // defaults to the list length, (default 8), set it explicitly only when supplying multi-match globs
|
|
289
344
|
tsconfigRootDir: process.cwd(), // defaults to the detected workspace root
|
|
290
345
|
},
|
|
291
|
-
}
|
|
292
|
-
);
|
|
346
|
+
},
|
|
347
|
+
});
|
|
293
348
|
```
|
|
294
349
|
|
|
295
350
|
#### Per-package configs (monorepo)
|
|
@@ -304,15 +359,15 @@ import rootConfig from '../../eslint.config.mjs';
|
|
|
304
359
|
export default defineConfig([...(await rootConfig), { rules: { 'tailwindcss/no-custom-classname': 'off' } }]);
|
|
305
360
|
```
|
|
306
361
|
|
|
307
|
-
…or
|
|
362
|
+
…or call `eslintConfig` again with the overrides this app needs, `apps/web/eslint.config.mjs`:
|
|
308
363
|
|
|
309
364
|
```js
|
|
310
365
|
import { fileURLToPath } from 'node:url';
|
|
311
366
|
import { defineConfig } from 'eslint/config';
|
|
312
|
-
import {
|
|
367
|
+
import { eslintConfig } from '@kirill.konshin/lint';
|
|
313
368
|
|
|
314
369
|
export default defineConfig(
|
|
315
|
-
await
|
|
370
|
+
await eslintConfig({
|
|
316
371
|
detection: { enabled: false, strict: true }, // fully explicit: this config only sees its own scope
|
|
317
372
|
// do not use workspace-wide auto-scan, provide exactly ONE from THIS leaf package
|
|
318
373
|
tailwind: { cssConfigPath: fileURLToPath(new URL('src/app/index.css', import.meta.url)) },
|
|
@@ -320,7 +375,7 @@ export default defineConfig(
|
|
|
320
375
|
);
|
|
321
376
|
```
|
|
322
377
|
|
|
323
|
-
⚠️ Nearest-wins means root-only blocks (e.g.
|
|
378
|
+
⚠️ Nearest-wins means root-only blocks (e.g. custom rules) do NOT apply to the subtree unless inherited or re-declared.
|
|
324
379
|
|
|
325
380
|
[Detection](#detection) runs against the **workspace root** even from a nested config, so per-app tool settings (`cssConfigPath`) should be explicit absolute paths — relative ones depend on the lint cwd.
|
|
326
381
|
|
|
@@ -346,35 +401,7 @@ export default {
|
|
|
346
401
|
|
|
347
402
|
Import from `/prettier`, not the package root: the root loads every ESLint plugin, which would slow down each Prettier run.
|
|
348
403
|
|
|
349
|
-
###
|
|
350
|
-
|
|
351
|
-
Oxfmt reads it too; `fmtConfig()` sets the Prettier behaviors that differ from it.
|
|
352
|
-
|
|
353
|
-
```editorconfig
|
|
354
|
-
root = true
|
|
355
|
-
|
|
356
|
-
[*]
|
|
357
|
-
indent_style = space
|
|
358
|
-
end_of_line = lf
|
|
359
|
-
charset = utf-8
|
|
360
|
-
trim_trailing_whitespace = true
|
|
361
|
-
insert_final_newline = false
|
|
362
|
-
max_line_length = 120
|
|
363
|
-
|
|
364
|
-
[*.md]
|
|
365
|
-
max_line_length = 99999
|
|
366
|
-
|
|
367
|
-
[*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}]
|
|
368
|
-
indent_size = 4
|
|
369
|
-
|
|
370
|
-
[*.{css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}]
|
|
371
|
-
indent_size = 2
|
|
372
|
-
|
|
373
|
-
[Makefile]
|
|
374
|
-
indent_style = tab
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
`package.json`:
|
|
404
|
+
### `package.json` (legacy for ESLint / Husky / Lint Staged)
|
|
378
405
|
|
|
379
406
|
```jsonc
|
|
380
407
|
{
|
|
@@ -392,7 +419,7 @@ indent_style = tab
|
|
|
392
419
|
- Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
|
|
393
420
|
- Prettier: `{**/*,*}.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue,css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}`
|
|
394
421
|
|
|
395
|
-
### Lint Staged
|
|
422
|
+
### Lint Staged (legacy, see VitePlus)
|
|
396
423
|
|
|
397
424
|
`.lintstagedrc.mjs`
|
|
398
425
|
|
|
@@ -454,21 +481,31 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
|
|
|
454
481
|
|
|
455
482
|
In the project root, `lint-prepare`:
|
|
456
483
|
|
|
457
|
-
- Creates real `rules/` and `skills/` directories in `.agents/` (canonical, cross-tool — Codex reads it) and `.claude/` (Claude Code)
|
|
458
|
-
- Links every `rules/*.md` file
|
|
484
|
+
- Creates real `rules/` and `skills/` directories in `.agents/` (canonical, cross-tool — Codex reads it) and `.claude/` (Claude Code).
|
|
485
|
+
- Links every `rules/*.md` file into both, except the ones the `rules` map of [`lint.config.ts`](#lintconfigts) turns off (`rules: { redux: false }`). Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package). A rule of yours with the same name in `.agents/` wins, the package one is not installed.
|
|
486
|
+
- Installs the skills of the `skills` map of `lint.config.ts`, merged over the defaults, with the [`skills` CLI](https://github.com/vercel-labs/skills), into `.agents/skills/` and from there into `.claude/skills/`. The map is keyed by source, each value uses the toggle notation; `skills: { name: true | false }` picks skills of a source — with no `true` entry every skill except the `false` ones:
|
|
487
|
+
- npm packages (`@scope/name`, or a name without `/`) are dependencies that ship skills: `skills experimental_sync -y -a codex claude-code` links every `skills/<name>/` folder of your dependencies; the map only leaves some out (`--exclude`). Default: this package's own skills (`'@kirill.konshin/lint': true`) — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules.
|
|
488
|
+
- Git sources (`owner/repo`) are installed with `skills add`, at `ref` when set (pin a full 40-character commit SHA). A source whose skills `skills-lock.json` already has at the same ref is not fetched again. `lint.config.ts` owns the remote skills of `skills-lock.json`: a remote skill it no longer lists is removed (`skills remove`).
|
|
489
|
+
- Defaults — every project gets them, turn off what it does not need: the [Core Pack](https://skills.sh/p/DxVN7q53wGdAcZQt) (`vercel-labs/agent-skills` incl. `web-design-guidelines`, `vercel/ai`, `shadcn-ui/ui`, `heroui-inc/heroui`, `mui/material-ui` without `material-ui-tailwind`, `neondatabase/agent-skills`) and the official skills of the libraries the rules cover (`vercel/next.js`, `reduxjs/redux-toolkit`, `vercel/turborepo`, `nrwl/nx-ai-agents-config`, `expo/skills`, `microsoft/playwright-cli`). Each source lists its skills and pins a commit: `DEFAULT_LINT_CONFIG` in `src/config.ts`.
|
|
490
|
+
- A skill folder of yours with the same name in `.agents/skills/` wins.
|
|
491
|
+
- A failed CLI run is a warning, the install goes on: run `lint-prepare` again.
|
|
492
|
+
- On CI (`CI` set) nothing remote is fetched (`--no-remote`, no `skills add`): no network needed.
|
|
493
|
+
- Telemetry is off (`DISABLE_TELEMETRY=1`) unless you set it.
|
|
494
|
+
- It writes `skills-lock.json`: add it to `.gitignore`, `lint-prepare` creates it again on every install.
|
|
495
|
+
- A personal skill (`~/.claude/skills`) overrides a project skill with the same name in Claude Code.
|
|
459
496
|
- Mirrors your own top-level entries from `.agents/{rules,skills}/` into `.claude/`. Commands are not synced: make them skills.
|
|
460
|
-
- Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs, including what older versions placed (
|
|
497
|
+
- Removes dead links (e.g. after renaming a file) and the links it placed before but no longer needs, including what older versions placed (skill links, `commands/`). Each directory gets a generated `.gitignore` listing its links and the skills the `skills` CLI installed, so your own entries stay tracked.
|
|
461
498
|
- Writes an empty marker pair for each section another tool owns into the generated `AGENTS.md` — currently Vite+ (`<!--VITE PLUS START-->`). The tool fills it, so run it **after** `lint-prepare` in the same install script (`lint-prepare init && vp config`): tools write their own agent content, nothing is copied by hand.
|
|
462
499
|
- Generates `AGENTS.md` for other assistants (Codex, Cursor, Copilot, …) with a `# Rules` section — one entry per rule (the package's and yours): its title, frontmatter `description`, the `paths` it is scoped to and a plain link to its `.agents/rules/<file>` entry — and symlinks `CLAUDE.md` to it. The links are never `@` imports: Claude Code loads `.claude/rules` itself and honours each rule's `paths`, while an import would load every rule into every session.
|
|
463
500
|
|
|
464
501
|
### OpenSpec
|
|
465
502
|
|
|
466
|
-
For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpec) the package ships one bin, `spec-tools` — a single self-contained file, `skills/spec-tools/scripts/cli.js` —
|
|
503
|
+
For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpec) the package ships one bin, `spec-tools` — a single self-contained file, `skills/spec-tools/scripts/cli.js` — four skills:
|
|
467
504
|
|
|
468
505
|
- `spec-tools steward` and the `spec-steward` skill — the corpus gate (citations, binding, the scenario ratchet), the edit hook, corpus-quality audits and review rounds.
|
|
469
506
|
- `spec-tools` and its skill — the change gates, the workflow-evidence gate, the requirement-level specification diff, the code-conformance audit, and the glue a CI pipeline runs around a headless AI review (verdict gate, merge-request comment, HTML reports).
|
|
470
507
|
- `spec-verify` — the skill every audit worker loads.
|
|
471
|
-
-
|
|
508
|
+
- `spec-author` — the skill that writes or edits a specification in place, the default direct-edit path (`/spec-author`).
|
|
472
509
|
|
|
473
510
|
Which to reach for:
|
|
474
511
|
|
|
@@ -550,6 +587,16 @@ Setup and the GitLab pipeline are in the `spec-tools` skill.
|
|
|
550
587
|
|
|
551
588
|
Only the files `lint-prepare` knows (package files and mirrors of yours) and dead links are touched: real files are never overwritten (e.g. your own `.claude/rules/*.md`) and nothing is written through a symlinked directory. `.codex/` is not touched: Codex reads `.agents/skills` and `AGENTS.md`, and the links earlier versions placed in `.codex/` stay until you delete them. `init`/`update` refuse to run if `CLAUDE.md` isn't a symlink. If `AGENTS.md` exists and wasn't generated by this tool, `init` skips it; use `update` to force regeneration.
|
|
552
589
|
|
|
590
|
+
## Migration
|
|
591
|
+
|
|
592
|
+
Upgrading between minor versions: the `lint-migrate` skill, one section per version step. 0.7 → 0.8 in short:
|
|
593
|
+
|
|
594
|
+
- One [`lint.config.ts`](#lintconfigts) in the workspace root holds every setting, `"type": "module"` in the root `package.json`; the entry points take overrides only
|
|
595
|
+
- ESLint: `defineLintConfig(options)` → `eslintConfig(overrides)`; `typeAware` and `defaultIgnore` → the `eslint` key
|
|
596
|
+
- Vite+: `vite.config.ts` becomes `defineConfig(vitePlusConfig())`; its blocks (`lint`, `fmt`, `test`, …) and toggles move into `lint.config.ts`, `typeAware` and the blocks under the `vitePlus` key; `vitePlusConfig` is now async
|
|
597
|
+
- Skills: the root `package.json` `skills` field → the `skills` map of `lint.config.ts`; package rules can be turned off with the `rules` map
|
|
598
|
+
- `vite-plus` is a required peer, also without Vite+ (it types `lint.config.ts`)
|
|
599
|
+
|
|
553
600
|
## Development
|
|
554
601
|
|
|
555
602
|
### Build
|
|
@@ -558,13 +605,13 @@ Only the files `lint-prepare` knows (package files and mirrors of yours) and dea
|
|
|
558
605
|
|
|
559
606
|
### ESLint and Vite+ configs
|
|
560
607
|
|
|
561
|
-
`src/
|
|
608
|
+
`src/config.ts` is the `lint.config.ts` schema, its defaults and its loader (the `./config` entry, no ESLint plugin). `src/gates.ts` holds every tool gate once; the ESLint blocks and `src/vitePlus.ts` both call it. `src/vitePlus.ts` reuses the conventions (`src/conventions.ts`) of the ESLint blocks and imports no ESLint plugin: it references the JS plugins by resolved path. `src/oxlintPlugin.ts` is the Oxlint JS plugin with the custom rules.
|
|
562
609
|
|
|
563
610
|
Declarations are generated from the TypeScript source and retain the underlying package types — `Linter.Config`, Tailwind plugin settings, Prettier `Config`, and lint-staged `Configuration`.
|
|
564
611
|
|
|
565
|
-
**Every** block lives in a themed `src/configs/*.ts` file and is exported as a standalone function for manual composition (and easy testing/mocking), in the order `
|
|
612
|
+
**Every** block lives in a themed `src/configs/*.ts` file and is exported as a standalone function for manual composition (and easy testing/mocking), in the order `eslintConfig` applies them: `baseConfig` (JS recommended + global ignores + globals + core-rule overrides), `defaultIgnoreConfig`, `reactConfig` (the whole React family, see below), `prettierConfig`, `storybookConfig`, `typeAwareConfig` (off by default; ordered before the import blocks so its naming-convention rule loses to the default-export relaxation), `importXConfig` (includes the default-export relaxation for conventional files), `importSortConfig`, `unusedImportsConfig`, `promiseConfig`, `unicornConfig`, `turboConfig`, `tailwindConfig`, `nxConfig`, `jestConfig`, `vitestConfig`, `testConfig`.
|
|
566
613
|
|
|
567
|
-
Tool-gated functions take the same value as their `
|
|
614
|
+
Tool-gated functions take the same value as their `lint.config.ts` key and gate themselves (`tailwindConfig(true)`, `nxConfig(false)` → `[]`, `tailwindConfig({ cssConfigPath })`). `reactConfig(nextFlag, strict)` is the whole family in its load-bearing order — Next is just a shortcut to an opinionated React/TypeScript setup, so the TS wiring, overrides and settings apply no matter whether Next or plain React won: `nextConfig` (chooser: `nextBaseConfig` when Next is enabled, `reactBaseConfig` fallback otherwise) → `typescriptOverridesConfig` → `nextOverridesConfig` → `reactSettingsConfig` — all exported individually too.
|
|
568
615
|
|
|
569
616
|
### Detection
|
|
570
617
|
|
|
@@ -627,9 +674,9 @@ Due to limitations package visibility between leaf and root this package has to
|
|
|
627
674
|
|
|
628
675
|
¹ the plugins need the tool's package resolvable at lint time (`tailwindcss` for the theme-loading workers, `next` for `eslint-config-next`'s internal `require`s, `storybook` for its plugin's static import, `jest` for version sniffing) — resolvable from the workspace root, or the hard error of step 3 fires.
|
|
629
676
|
|
|
630
|
-
`vitePlusConfig` runs the same gates, with three differences: Oxlint JS plugins load from this package, so only `storybook` (its plugin imports `storybook`) and `nx` (needs `eslint`) demand a resolvable package; `vitest` is ON unless set to `false` (Vite+ bundles it); `next` needs no package (Oxlint's `nextjs` plugin is native).
|
|
677
|
+
`vitePlusConfig` runs the same gates (`src/gates.ts`, shared with the ESLint blocks), with three differences: Oxlint JS plugins load from this package, so only `storybook` (its plugin imports `storybook`) and `nx` (needs `eslint`) demand a resolvable package; `vitest` is ON unless set to `false` (Vite+ bundles it); `next` needs no package (Oxlint's `nextjs` plugin is native). `typeAware` differs by backend: `eslint.typeAware` is OFF by default (slow), `vitePlus.typeAware` ON.
|
|
631
678
|
|
|
632
|
-
The machinery is controlled by the `detection`
|
|
679
|
+
The machinery is controlled by the `detection` key of `lint.config.ts` (same toggle notation as the tools):
|
|
633
680
|
|
|
634
681
|
- `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (step 2)
|
|
635
682
|
- `detection: { strict: true }` — only step 1 runs: the `has*` package probes **are** the strict detection — no workspace evidence scans (2). Mandatory settings (`cssConfigPath`) must then be explicit, and `nx.json` is checked at **cwd** instead of the workspace root (`hasNx` is the only non-package `has*`)
|
|
@@ -637,7 +684,7 @@ The machinery is controlled by the `detection` option (same toggle notation as t
|
|
|
637
684
|
|
|
638
685
|
Set `LINT_DEBUG=1` to trace the machinery: `has*` probe results, every workspace scan (glob, root, files found) and each tool's gate verdict (supplied options, absolutized & scanned evidence files, effective enabled status + reason).
|
|
639
686
|
|
|
640
|
-
> `basePath: 'packages/xxx'` (ESLint ≥ 9.30) can scope a config object to a directory within a single root config, but it won't help with detection — `
|
|
687
|
+
> `basePath: 'packages/xxx'` (ESLint ≥ 9.30) can scope a config object to a directory within a single root config, but it won't help with detection — `eslintConfig` detects once, workspace-wide (e.g. Tailwind still demands exactly one entry CSS), so per-app settings would still have to be spelled out block by block; nested configs are the cleaner tool for this.
|
|
641
688
|
|
|
642
689
|
### Type-aware rules (optional, disabled by default for performance)
|
|
643
690
|
|
|
@@ -657,7 +704,7 @@ paths:
|
|
|
657
704
|
## Issues
|
|
658
705
|
|
|
659
706
|
- Package managers
|
|
660
|
-
- [ ] TODO verify the package end-to-end (workspace-root detection, Tailwind / `next.config.*` scans, `has*` capability probes, plugin resolution, `
|
|
707
|
+
- [ ] TODO verify the package end-to-end (workspace-root detection, Tailwind / `next.config.*` scans, `has*` capability probes, plugin resolution, `eslintConfig` under a real lint run) with each manager:
|
|
661
708
|
- [x] Yarn Berry, node-modules linker — this repo, fully covered
|
|
662
709
|
- [ ] Yarn Berry **PnP** — root-declared `tailwindcss` verified working (see "Detection" step 4); full config run (plugin loading, capability probes) unverified since the switch to `@manypkg/find-root`/`local-pkg`
|
|
663
710
|
- [ ] Yarn 1 (classic) — root detection now delegates to `@manypkg/find-root` (workspace-manifest walk); unverified since the switch
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { tsExts } from "./exts.js";
|
|
2
|
+
import { scanWorkspace } from "./lib.js";
|
|
3
|
+
import { ParserOptions } from "@typescript-eslint/parser";
|
|
4
|
+
import { PluginSettings } from "eslint-plugin-tailwindcss";
|
|
5
|
+
import { UserConfig } from "vite-plus";
|
|
6
|
+
//#region src/config.d.ts
|
|
7
|
+
type ProjectServiceOptions = Exclude<NonNullable<ParserOptions['projectService']>, boolean>;
|
|
8
|
+
export type ToggleOptions = {
|
|
9
|
+
enabled?: boolean;
|
|
10
|
+
};
|
|
11
|
+
export type DetectionOptions = ToggleOptions & {
|
|
12
|
+
strict?: boolean;
|
|
13
|
+
};
|
|
14
|
+
export type NextOptions = ToggleOptions & {
|
|
15
|
+
rootDir?: string | string[];
|
|
16
|
+
};
|
|
17
|
+
export type TailwindOptions = ToggleOptions & {
|
|
18
|
+
cssConfigPath?: PluginSettings['cssConfigPath'];
|
|
19
|
+
scoped?: boolean;
|
|
20
|
+
};
|
|
21
|
+
export type TypeAwareOptions = ToggleOptions & Pick<ProjectServiceOptions, 'allowDefaultProject' | 'maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING'> & {
|
|
22
|
+
tsconfigRootDir?: ParserOptions['tsconfigRootDir'];
|
|
23
|
+
};
|
|
24
|
+
export type DefaultIgnoreOptions = {
|
|
25
|
+
enabled: false;
|
|
26
|
+
importMetaUrl?: string;
|
|
27
|
+
} | {
|
|
28
|
+
enabled?: true;
|
|
29
|
+
importMetaUrl: string;
|
|
30
|
+
};
|
|
31
|
+
/** Settings of the ESLint config only. */
|
|
32
|
+
export type EslintOptions = {
|
|
33
|
+
/** Off by default: type-aware ESLint rules are slow. */
|
|
34
|
+
typeAware?: boolean | TypeAwareOptions;
|
|
35
|
+
defaultIgnore?: boolean | DefaultIgnoreOptions;
|
|
36
|
+
};
|
|
37
|
+
/**
|
|
38
|
+
* Settings of the Vite+ config only, plus the project's own Vite+ blocks (`lint`, `fmt`, `staged`, `test`, `pack`, ...),
|
|
39
|
+
* which `vitePlusConfig()` merges over its defaults: lists add up, maps merge by key, `staged` replaces the default.
|
|
40
|
+
*/
|
|
41
|
+
export type VitePlusOptions = UserConfig & {
|
|
42
|
+
/** On by default: `vp check` is the type check (tsgolint). */
|
|
43
|
+
typeAware?: boolean | ToggleOptions;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* One skill source. `skills` names skills of the source: `true` installs one, `false` leaves one out. With no `true`
|
|
47
|
+
* entry, every skill of the source is installed except the `false` ones.
|
|
48
|
+
*/
|
|
49
|
+
export type SkillSourceOptions = ToggleOptions & {
|
|
50
|
+
/** Git ref of a remote source. */
|
|
51
|
+
ref?: string;
|
|
52
|
+
skills?: Record<string, boolean>;
|
|
53
|
+
};
|
|
54
|
+
/**
|
|
55
|
+
* Skill sources, keyed by source: a git source (`owner/repo`) is installed with `skills add`; an npm package
|
|
56
|
+
* (`@scope/name` or a name without `/`) is a dependency that ships skills, synced with `skills experimental_sync`.
|
|
57
|
+
* `false` is `{ enabled: false }`.
|
|
58
|
+
*/
|
|
59
|
+
export type SkillsConfig = Record<string, boolean | SkillSourceOptions>;
|
|
60
|
+
export type LintConfig = {
|
|
61
|
+
detection?: boolean | DetectionOptions;
|
|
62
|
+
next?: boolean | NextOptions;
|
|
63
|
+
storybook?: boolean | ToggleOptions;
|
|
64
|
+
turbo?: boolean | ToggleOptions;
|
|
65
|
+
nx?: boolean | ToggleOptions;
|
|
66
|
+
jest?: boolean | ToggleOptions;
|
|
67
|
+
vitest?: boolean | ToggleOptions;
|
|
68
|
+
tailwind?: boolean | TailwindOptions;
|
|
69
|
+
eslint?: EslintOptions;
|
|
70
|
+
vitePlus?: VitePlusOptions;
|
|
71
|
+
/** Skills `lint-prepare` installs, merged over {@link DEFAULT_LINT_CONFIG}. */
|
|
72
|
+
skills?: SkillsConfig;
|
|
73
|
+
/** Package rules by name (file name without `.md`): `false` leaves a rule out. */
|
|
74
|
+
rules?: Record<string, boolean>;
|
|
75
|
+
};
|
|
76
|
+
export declare const LINT_CONFIG_FILE = "lint.config.ts";
|
|
77
|
+
/**
|
|
78
|
+
* The base every resolved config starts from. Every project gets every skill below; `lint.config.ts` turns off what it
|
|
79
|
+
* does not need (`'expo/skills': false`).
|
|
80
|
+
*
|
|
81
|
+
* Remote sources follow the Core Pack https://skills.sh/p/DxVN7q53wGdAcZQt (synced by hand, see the repository's
|
|
82
|
+
* `curated-skills-update` skill), plus the official skills of the libraries the rules cover. Each source lists its
|
|
83
|
+
* skills: the repositories also hold their maintainers' internal skills. `ref` pins a full commit SHA.
|
|
84
|
+
*/
|
|
85
|
+
export declare const DEFAULT_LINT_CONFIG: LintConfig;
|
|
86
|
+
/** Type-checks `lint.config.ts`; returns the config as it is. */
|
|
87
|
+
export declare function defineLintConfig(config: LintConfig): LintConfig;
|
|
88
|
+
/**
|
|
89
|
+
* Deep merge, `override` wins. Objects merge key by key, arrays and other values are replaced. A boolean over an
|
|
90
|
+
* options object keeps the options and sets `enabled` (`false` over `{ ref }` is `{ ref, enabled: false }`); an options
|
|
91
|
+
* object over a boolean replaces it (options imply `enabled: true`).
|
|
92
|
+
*/
|
|
93
|
+
export declare function mergeLintConfig<T>(base: T, override: unknown): T;
|
|
94
|
+
/**
|
|
95
|
+
* The `lint.config.ts` of the workspace root, `{}` when there is none. Only the root is read: a monorepo has one config,
|
|
96
|
+
* packages differ through the arguments of the entry points. Node loads the file natively (type stripping), so it must
|
|
97
|
+
* use only erasable TypeScript syntax. Cached per root.
|
|
98
|
+
*/
|
|
99
|
+
export declare function loadLintConfig(root?: string): Promise<LintConfig>;
|
|
100
|
+
/** {@link DEFAULT_LINT_CONFIG}, then the root `lint.config.ts`, then `overrides`, merged deep. */
|
|
101
|
+
export declare function resolveLintConfig(overrides?: LintConfig, root?: string): Promise<LintConfig>;
|
|
102
|
+
//#endregion
|
|
103
|
+
export { scanWorkspace, tsExts };
|