@kirill.konshin/lint 0.7.4 → 0.8.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.
Files changed (56) hide show
  1. package/README.md +161 -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 +65 -47
  29. package/package.json +7 -4
  30. package/rules/agent.md +1 -0
  31. package/rules/db.md +1 -0
  32. package/rules/expo.md +2 -0
  33. package/rules/mui.md +3 -1
  34. package/rules/nextjs.md +3 -3
  35. package/rules/react.md +4 -28
  36. package/rules/tailwind.md +3 -2
  37. package/rules/typescript.md +1 -1
  38. package/rules/vite.md +1 -1
  39. package/skills/lint-db/SKILL.md +11 -9
  40. package/skills/lint-electron/SKILL.md +3 -1
  41. package/skills/lint-github/SKILL.md +10 -2
  42. package/skills/lint-gitlab/SKILL.md +17 -2
  43. package/skills/lint-migrate/SKILL.md +17 -1
  44. package/skills/lint-mui/SKILL.md +15 -18
  45. package/skills/lint-nextjs/SKILL.md +30 -18
  46. package/skills/lint-npm-yarn/SKILL.md +16 -30
  47. package/skills/lint-repo/SKILL.md +6 -6
  48. package/skills/lint-tailwind/SKILL.md +8 -8
  49. package/skills/lint-webstorm/SKILL.md +1 -1
  50. package/skills/lint-worktree/SKILL.md +25 -9
  51. package/skills/spec-steward/SKILL.md +1 -1
  52. package/skills/spec-steward/references/contract.md +1 -1
  53. package/skills/spec-steward/references/wiring.md +1 -1
  54. package/skills/spec-tools/SKILL.md +2 -2
  55. package/skills/spec-tools/scripts/cli.js +2 -2
  56. 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,91 @@ 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()`
173
+ - Rolldown module-directive warnings (`'use server'`, `'use client'`) default off for builds and dependency optimization; set `build.rolldownOptions.checks.moduleLevelDirective` or `optimizeDeps.rolldownOptions.checks.moduleLevelDirective` to `true` to re-enable. This changes logging only, not directive handling.
112
174
  - 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
175
  - `.gitignore` and `.prettierignore` are honoured by Oxfmt; the recommended `.prettierignore` entries are default `fmt.ignorePatterns`, add others there
114
176
 
@@ -154,7 +216,7 @@ What maps where:
154
216
  </tbody>
155
217
  </table>
156
218
 
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`).
219
+ 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
220
 
159
221
  `package.json`:
160
222
 
@@ -182,10 +244,38 @@ vp staged
182
244
 
183
245
  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
246
 
185
- ## ESLint + Prettier (without Vite+)
247
+ ## Editor Config `.editorconfig`
248
+
249
+ Oxfmt reads it too; `fmtConfig()` sets the Prettier behaviors that differ from it.
250
+
251
+ ```editorconfig
252
+ root = true
253
+
254
+ [*]
255
+ indent_style = space
256
+ end_of_line = lf
257
+ charset = utf-8
258
+ trim_trailing_whitespace = true
259
+ insert_final_newline = false
260
+ max_line_length = 120
261
+
262
+ [*.md]
263
+ max_line_length = 99999
264
+
265
+ [*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}]
266
+ indent_size = 4
267
+
268
+ [*.{css,scss,sass,less,yml,yaml,json,json5,graphql,graphqls,xml}]
269
+ indent_size = 2
270
+
271
+ [Makefile]
272
+ indent_style = tab
273
+ ```
274
+
275
+ ## ESLint + Prettier (without Vite+, legacy, not recommended)
186
276
 
187
277
  ```bash
188
- $ yarn add -D eslint prettier @kirill.konshin/lint @yarnpkg/types husky lint-staged
278
+ $ yarn add -D eslint prettier vite-plus @kirill.konshin/lint @yarnpkg/types husky lint-staged
189
279
  ```
190
280
 
191
281
  ### `.prettierignore`
@@ -211,28 +301,24 @@ https://prettier.io/docs/ignore:
211
301
 
212
302
  `eslint.config.mjs`:
213
303
 
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:
304
+ 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
305
 
216
306
  ```js
217
307
  import { defineConfig } from 'eslint/config';
218
- import { defineLintConfig } from '@kirill.konshin/lint';
308
+ import { eslintConfig } from '@kirill.konshin/lint';
219
309
 
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
- );
310
+ // every tool integration auto-detected, settings from lint.config.ts
311
+ export default defineConfig(await eslintConfig());
226
312
  ```
227
313
 
228
- Config can be extended, `defineLintConfig` returns a `Promise` (natively awaited by ESLint), to compose with your own blocks, `await` it:
314
+ `eslintConfig` returns a `Promise` (natively awaited by ESLint), to compose with your own blocks, `await` it:
229
315
 
230
316
  ```js
231
317
  import { defineConfig } from 'eslint/config';
232
- import { defineLintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
318
+ import { eslintConfig, includeIgnoreFile } from '@kirill.konshin/lint';
233
319
 
234
320
  export default defineConfig([
235
- ...(await defineLintConfig({ defaultIgnore: { importMetaUrl: import.meta.url } })),
321
+ ...(await eslintConfig({ eslint: { defaultIgnore: { importMetaUrl: import.meta.url } } })),
236
322
  {
237
323
  name: 'Custom rules',
238
324
  rules: {
@@ -243,53 +329,23 @@ export default defineConfig([
243
329
  ]);
244
330
  ```
245
331
 
246
- #### Full Config Example
332
+ #### Type-aware file list
247
333
 
248
- Default behavior in the comments, all tools are optional (see [Detection](#detection)). Enable/disable tools using:
334
+ `eslint.typeAware` takes the typescript-eslint project service options:
249
335
 
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
- },
336
+ ```ts
337
+ import { defineLintConfig, scanWorkspace } from '@kirill.konshin/lint/config';
284
338
 
339
+ export default defineLintConfig({
340
+ eslint: {
285
341
  // OFF by default (slow) - see "Type-aware rules"
286
342
  typeAware: {
287
343
  allowDefaultProject: scanWorkspace('{vite,vitest}.config.ts'), // no default; absolute paths are relativized; ** globs are not supported
288
344
  maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 50, // defaults to the list length, (default 8), set it explicitly only when supplying multi-match globs
289
345
  tsconfigRootDir: process.cwd(), // defaults to the detected workspace root
290
346
  },
291
- }),
292
- );
347
+ },
348
+ });
293
349
  ```
294
350
 
295
351
  #### Per-package configs (monorepo)
@@ -304,15 +360,15 @@ import rootConfig from '../../eslint.config.mjs';
304
360
  export default defineConfig([...(await rootConfig), { rules: { 'tailwindcss/no-custom-classname': 'off' } }]);
305
361
  ```
306
362
 
307
- …or simply call `defineLintConfig` again with the options this app needs, `apps/web/eslint.config.mjs`:
363
+ …or call `eslintConfig` again with the overrides this app needs, `apps/web/eslint.config.mjs`:
308
364
 
309
365
  ```js
310
366
  import { fileURLToPath } from 'node:url';
311
367
  import { defineConfig } from 'eslint/config';
312
- import { defineLintConfig } from '@kirill.konshin/lint';
368
+ import { eslintConfig } from '@kirill.konshin/lint';
313
369
 
314
370
  export default defineConfig(
315
- await defineLintConfig({
371
+ await eslintConfig({
316
372
  detection: { enabled: false, strict: true }, // fully explicit: this config only sees its own scope
317
373
  // do not use workspace-wide auto-scan, provide exactly ONE from THIS leaf package
318
374
  tailwind: { cssConfigPath: fileURLToPath(new URL('src/app/index.css', import.meta.url)) },
@@ -320,7 +376,7 @@ export default defineConfig(
320
376
  );
321
377
  ```
322
378
 
323
- ⚠️ Nearest-wins means root-only blocks (e.g. `defaultIgnore`, custom rules) do NOT apply to the subtree unless inherited or re-declared.
379
+ ⚠️ Nearest-wins means root-only blocks (e.g. custom rules) do NOT apply to the subtree unless inherited or re-declared.
324
380
 
325
381
  [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
382
 
@@ -346,35 +402,7 @@ export default {
346
402
 
347
403
  Import from `/prettier`, not the package root: the root loads every ESLint plugin, which would slow down each Prettier run.
348
404
 
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`:
405
+ ### `package.json` (legacy for ESLint / Husky / Lint Staged)
378
406
 
379
407
  ```jsonc
380
408
  {
@@ -392,7 +420,7 @@ indent_style = tab
392
420
  - Eslint: `**/*.{js,jsx,ts,tsx,cjs,cts,mjs,mts,md,mdx,htm,html,vue}`
393
421
  - 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
422
 
395
- ### Lint Staged
423
+ ### Lint Staged (legacy, see VitePlus)
396
424
 
397
425
  `.lintstagedrc.mjs`
398
426
 
@@ -454,21 +482,31 @@ The generated `AGENTS.md` has a `# Custom Rules` section at the bottom — add p
454
482
 
455
483
  In the project root, `lint-prepare`:
456
484
 
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.
485
+ - Creates real `rules/` and `skills/` directories in `.agents/` (canonical, cross-tool — Codex reads it) and `.claude/` (Claude Code).
486
+ - 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.
487
+ - 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:
488
+ - 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.
489
+ - 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`).
490
+ - 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`.
491
+ - A skill folder of yours with the same name in `.agents/skills/` wins.
492
+ - A failed CLI run is a warning, the install goes on: run `lint-prepare` again.
493
+ - On CI (`CI` set) nothing remote is fetched (`--no-remote`, no `skills add`): no network needed.
494
+ - Telemetry is off (`DISABLE_TELEMETRY=1`) unless you set it.
495
+ - It writes `skills-lock.json`: add it to `.gitignore`, `lint-prepare` creates it again on every install.
496
+ - A personal skill (`~/.claude/skills`) overrides a project skill with the same name in Claude Code.
459
497
  - 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.
498
+ - 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
499
  - 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
500
  - 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
501
 
464
502
  ### OpenSpec
465
503
 
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:
504
+ 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
505
 
468
506
  - `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
507
  - `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
508
  - `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.
509
+ - `spec-author` — the skill that writes or edits a specification in place, the default direct-edit path (`/spec-author`).
472
510
 
473
511
  Which to reach for:
474
512
 
@@ -550,6 +588,16 @@ Setup and the GitLab pipeline are in the `spec-tools` skill.
550
588
 
551
589
  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
590
 
591
+ ## Migration
592
+
593
+ Upgrading between minor versions: the `lint-migrate` skill, one section per version step. 0.7 → 0.8 in short:
594
+
595
+ - 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
596
+ - ESLint: `defineLintConfig(options)` → `eslintConfig(overrides)`; `typeAware` and `defaultIgnore` → the `eslint` key
597
+ - 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
598
+ - Skills: the root `package.json` `skills` field → the `skills` map of `lint.config.ts`; package rules can be turned off with the `rules` map
599
+ - `vite-plus` is a required peer, also without Vite+ (it types `lint.config.ts`)
600
+
553
601
  ## Development
554
602
 
555
603
  ### Build
@@ -558,13 +606,13 @@ Only the files `lint-prepare` knows (package files and mirrors of yours) and dea
558
606
 
559
607
  ### ESLint and Vite+ configs
560
608
 
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.
609
+ `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
610
 
563
611
  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
612
 
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`.
613
+ **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
614
 
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.
615
+ 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
616
 
569
617
  ### Detection
570
618
 
@@ -627,9 +675,9 @@ Due to limitations package visibility between leaf and root this package has to
627
675
 
628
676
  ¹ 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
677
 
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).
678
+ `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
679
 
632
- The machinery is controlled by the `detection` option (same toggle notation as the tools):
680
+ The machinery is controlled by the `detection` key of `lint.config.ts` (same toggle notation as the tools):
633
681
 
634
682
  - `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (step 2)
635
683
  - `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 +685,7 @@ The machinery is controlled by the `detection` option (same toggle notation as t
637
685
 
638
686
  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
687
 
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.
688
+ > `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
689
 
642
690
  ### Type-aware rules (optional, disabled by default for performance)
643
691
 
@@ -657,7 +705,7 @@ paths:
657
705
  ## Issues
658
706
 
659
707
  - 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:
708
+ - [ ] 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
709
  - [x] Yarn Berry, node-modules linker — this repo, fully covered
662
710
  - [ ] 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
711
  - [ ] 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 };