@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.
Files changed (74) hide show
  1. package/README.md +160 -113
  2. package/dist/config.d.ts +103 -0
  3. package/dist/config.js +112 -0
  4. package/dist/configs/base.d.ts +1 -1
  5. package/dist/configs/nx.d.ts +1 -1
  6. package/dist/configs/nx.js +3 -8
  7. package/dist/configs/react.d.ts +3 -3
  8. package/dist/configs/react.js +6 -16
  9. package/dist/configs/storybook.d.ts +3 -3
  10. package/dist/configs/storybook.js +4 -9
  11. package/dist/configs/tailwind.d.ts +6 -25
  12. package/dist/configs/tailwind.js +3 -64
  13. package/dist/configs/testing.d.ts +1 -1
  14. package/dist/configs/testing.js +3 -15
  15. package/dist/configs/turbo.d.ts +2 -2
  16. package/dist/configs/turbo.js +4 -6
  17. package/dist/configs/typescriptTypeAware.d.ts +1 -1
  18. package/dist/gates.d.ts +72 -0
  19. package/dist/gates.js +132 -0
  20. package/dist/index.d.ts +15 -51
  21. package/dist/index.js +16 -14
  22. package/dist/lib.d.ts +1 -1
  23. package/dist/lib.js +1 -1
  24. package/dist/lintPrepare.d.ts +75 -28
  25. package/dist/lintPrepare.js +243 -35
  26. package/dist/testColocation.js +1 -1
  27. package/dist/vitePlus.d.ts +8 -18
  28. package/dist/vitePlus.js +40 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/auth.md +3 -3
  32. package/rules/db.md +6 -9
  33. package/rules/expo.md +2 -0
  34. package/rules/github.md +1 -1
  35. package/rules/gitlab.md +1 -1
  36. package/rules/i18n.md +3 -0
  37. package/rules/monorepo-turbo-nx.md +38 -4
  38. package/rules/mui.md +8 -18
  39. package/rules/nextjs.md +13 -13
  40. package/rules/npm-yarn.md +28 -118
  41. package/rules/nx.md +1 -1
  42. package/rules/playwright.md +1 -1
  43. package/rules/react.md +7 -32
  44. package/rules/tailwind.md +9 -47
  45. package/rules/testing.md +2 -2
  46. package/rules/turbo.md +1 -1
  47. package/rules/typescript.md +6 -2
  48. package/rules/ui-kit.md +6 -0
  49. package/rules/vite.md +1 -1
  50. package/skills/lint-db/SKILL.md +23 -0
  51. package/skills/lint-electron/SKILL.md +9 -6
  52. package/skills/lint-github/SKILL.md +15 -8
  53. package/skills/lint-gitlab/SKILL.md +20 -5
  54. package/skills/lint-migrate/SKILL.md +18 -2
  55. package/skills/lint-mui/SKILL.md +28 -0
  56. package/skills/lint-nextjs/SKILL.md +53 -16
  57. package/skills/lint-npm-yarn/SKILL.md +126 -0
  58. package/skills/lint-repo/SKILL.md +12 -12
  59. package/skills/lint-tailwind/SKILL.md +53 -0
  60. package/skills/lint-webstorm/SKILL.md +3 -3
  61. package/skills/lint-worktree/SKILL.md +25 -9
  62. package/skills/spec-author/SKILL.md +2 -2
  63. package/skills/spec-steward/SKILL.md +1 -1
  64. package/skills/spec-steward/references/apply.md +1 -1
  65. package/skills/spec-steward/references/contract.md +2 -2
  66. package/skills/spec-steward/references/model.md +2 -2
  67. package/skills/spec-steward/references/review-format.md +4 -4
  68. package/skills/spec-steward/references/wiring.md +2 -2
  69. package/skills/spec-steward/references/worker.md +1 -1
  70. package/skills/spec-tools/SKILL.md +2 -2
  71. package/skills/spec-tools/references/rules/common.md +1 -1
  72. package/skills/spec-tools/references/rules/spec-steward.md +1 -1
  73. package/skills/spec-tools/scripts/cli.js +2 -2
  74. 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/`, linked by `lint-prepare`).
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 — `vitePlusConfig` returns the `lint` (Oxlint), `fmt` (Oxfmt) and `staged` blocks; wrap it in `defineConfig` from `vite-plus`:
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(options)`, `fmtConfig()`, `stagedConfig()`
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
- ## ESLint + Prettier (without Vite+)
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). Pass options (JSDoc-typed, see `LintOptions` in `index.js`) to force any of them on/off or to supply tool-specific settings:
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 { defineLintConfig } from '@kirill.konshin/lint';
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
- Config can be extended, `defineLintConfig` returns a `Promise` (natively awaited by ESLint), to compose with your own blocks, `await` it:
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 { defineLintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
317
+ import { eslintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
233
318
 
234
319
  export default defineConfig([
235
- ...(await defineLintConfig({ defaultIgnore: { importMetaUrl: import.meta.url } })),
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
- #### Full Config Example
331
+ #### Type-aware file list
247
332
 
248
- Default behavior in the comments, all tools are optional (see [Detection](#detection)). Enable/disable tools using:
333
+ `eslint.typeAware` takes the typescript-eslint project service options:
249
334
 
250
- - `undefined` (default) — auto-detect, see [Detection](#detection)
251
- - `true` — force ON (use when detection misses a tool, can be useful to see the error why tool is missing)
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 simply call `defineLintConfig` again with the options this app needs, `apps/web/eslint.config.mjs`:
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 { defineLintConfig } from '@kirill.konshin/lint';
367
+ import { eslintConfig } from '@kirill.konshin/lint';
313
368
 
314
369
  export default defineConfig(
315
- await defineLintConfig({
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. `defaultIgnore`, custom rules) do NOT apply to the subtree unless inherited or re-declared.
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
- ### Editor Config `.editorconfig`
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), and symlinks the top-level entries it knows into them: a rule file, a skill folder.
458
- - Links every `rules/*.md` file and every `skills/<name>/` folder into both — e.g. `lint-repo`, which sets up the tooling above and audits the repo against the rules. Links point straight at the installed package's real location (`node_modules/@kirill.konshin/lint`, or the workspace package). A rule or skill of yours with the same name in `.agents/` wins, the package one is not installed.
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 (per-file skill links, `commands/`). Each directory gets a generated `.gitignore` listing its links, so your own entries stay tracked.
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` — three skills and a command:
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
- - `/spec-author` — the command that writes or edits a specification in place, the default direct-edit path.
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/vitePlus.ts` reuses the detection gates and 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.
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 `defineLintConfig` applies them: `baseConfig` (JS recommended + global ignores + globals + core-rule overrides), `defaultIgnoreConfig`, `reactConfig` (the whole React family, see below), `prettierConfig`, `storybookConfig`, `typeAwareConfig` (off by default; ordered before the import blocks so its naming-convention rule loses to the default-export relaxation), `importXConfig` (includes the default-export relaxation for conventional files), `importSortConfig`, `unusedImportsConfig`, `promiseConfig`, `unicornConfig`, `turboConfig`, `tailwindConfig`, `nxConfig`, `jestConfig`, `vitestConfig`, `testConfig`.
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 `defineLintConfig` flag and gate themselves (`tailwindConfig(true)`, `nxConfig(false)` → `[]`, `tailwindConfig({ cssConfigPath })`). `reactConfig(nextFlag, strict)` is the whole family in its load-bearing order — Next is just a shortcut to an opinionated React/TypeScript setup, so the TS wiring, overrides and settings apply no matter whether Next or plain React won: `nextConfig` (chooser: `nextBaseConfig` when Next is enabled, `reactBaseConfig` fallback otherwise) → `typescriptOverridesConfig` → `nextOverridesConfig` → `reactSettingsConfig` — all exported individually too.
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` option (same toggle notation as the tools):
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 — `defineLintConfig` detects once, workspace-wide (e.g. Tailwind still demands exactly one entry CSS), so per-app settings would still have to be spelled out block by block; nested configs are the cleaner tool for this.
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, `defineLintConfig` under a real lint run) with each manager:
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
@@ -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 };