@kirill.konshin/lint 0.6.7 → 0.7.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 (50) hide show
  1. package/README.md +253 -94
  2. package/dist/configs/imports.js +3 -30
  3. package/dist/configs/react.d.ts +0 -15
  4. package/dist/configs/react.js +2 -36
  5. package/dist/configs/tailwind.d.ts +10 -0
  6. package/dist/configs/tailwind.js +25 -9
  7. package/dist/configs/testing.js +2 -41
  8. package/dist/configs/unicorn.js +2 -10
  9. package/dist/conventions.d.ts +12 -0
  10. package/dist/conventions.js +53 -0
  11. package/dist/index.d.ts +4 -4
  12. package/dist/index.js +4 -4
  13. package/dist/lib.d.ts +18 -1
  14. package/dist/lib.js +36 -2
  15. package/dist/lintPrepare.d.ts +2 -1
  16. package/dist/lintPrepare.js +13 -1
  17. package/dist/oxlintPlugin.d.ts +10 -0
  18. package/dist/oxlintPlugin.js +13 -0
  19. package/dist/testColocation.d.ts +10 -0
  20. package/dist/testColocation.js +45 -0
  21. package/dist/vitePlus.d.ts +58 -0
  22. package/dist/vitePlus.js +434 -0
  23. package/package.json +32 -9
  24. package/rules/agent.md +3 -0
  25. package/rules/code-style.md +1 -1
  26. package/rules/github.md +4 -1
  27. package/rules/gitlab.md +3 -5
  28. package/rules/jest.md +1 -1
  29. package/rules/markdown.md +11 -0
  30. package/rules/monorepo-turbo-nx.md +9 -0
  31. package/rules/mui.md +0 -2
  32. package/rules/npm-yarn.md +10 -1
  33. package/rules/nx.md +3 -1
  34. package/rules/playwright.md +18 -0
  35. package/rules/react.md +1 -3
  36. package/rules/tailwind.md +1 -0
  37. package/rules/testing.md +5 -2
  38. package/rules/typescript.md +5 -4
  39. package/rules/vite.md +5 -1
  40. package/{rules/electron.md → skills/lint-electron/SKILL.md} +5 -3
  41. package/skills/lint-github/SKILL.md +244 -42
  42. package/skills/lint-gitlab/SKILL.md +46 -1
  43. package/skills/lint-migrate/SKILL.md +24 -0
  44. package/skills/lint-repo/SKILL.md +21 -5
  45. package/skills/lint-webstorm/SKILL.md +55 -3
  46. package/skills/spec-steward/SKILL.md +72 -15
  47. package/skills/spec-steward/references/contract.md +6 -6
  48. package/skills/spec-tools/SKILL.md +11 -11
  49. package/skills/spec-tools/references/rules/common.md +32 -7
  50. package/skills/spec-tools/scripts/cli.js +18 -12
package/README.md CHANGED
@@ -1,14 +1,20 @@
1
1
  # @kirill.konshin/lint
2
2
 
3
- ESLint + Prettier + lint-staged + Husky configuration, plus AI agent rules & skills for monorepos — in one package.
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
+
5
+ Upgrading from an older version: use the `lint-migrate` skill (shipped in `skills/`, linked by `lint-prepare`).
4
6
 
5
7
  ## Installation
6
8
 
9
+ Recommended, with [Vite+](#vite-recommended):
10
+
7
11
  ```bash
8
- $ yarn add -D eslint prettier @kirill.konshin/lint @yarnpkg/types husky lint-staged
12
+ $ yarn add -D vite-plus @kirill.konshin/lint @yarnpkg/types
9
13
  ```
10
14
 
11
- Every project whose `packageManager` is Yarn must directly install `@yarnpkg/types`; Yarn PnP does not allow `yarn.config.cjs` to require a transitive dependency.
15
+ Without Vite+, see [ESLint + Prettier](#eslint--prettier-without-vite).
16
+
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).
12
18
 
13
19
  ### PNPM
14
20
 
@@ -35,6 +41,17 @@ module.exports = defineConfig(defineYarnConfig());
35
41
 
36
42
  When the root has no `overrides` field, `@types/node`, `@types/react`, `@types/react-dom`, `next`, `eslint`, `typescript`, and `vite` must each use one range across the workspace. The root declaration wins; otherwise the first leaf path supplies the range. Run `yarn constraints --fix` to apply unambiguous changes.
37
43
 
44
+ With Vite+, `vite` is an alias of the Vite+ core and `vitest` is the version Vite+ bundles — pin both at the root:
45
+
46
+ ```json
47
+ {
48
+ "devDependencies": { "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0", "vite-plus": "^1.3.0" },
49
+ "resolutions": { "vite": "npm:@voidzero-dev/vite-plus-core@^1.3.0", "vitest": "5.0.5" }
50
+ }
51
+ ```
52
+
53
+ `@vitest/*` packages (`coverage-v8`, `web-worker`, …) must match the bundled Vitest exactly (`5.0.5`), or `vp test` refuses to run coverage.
54
+
38
55
  ## `.gitignore`
39
56
 
40
57
  ```gitignore
@@ -67,9 +84,109 @@ yarn-error*
67
84
  !.yarn/versions
68
85
  ```
69
86
 
70
- List need to be verified, especially `build`, `coverage`, `dist` must be verified not to exclude legit folders.
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
+
89
+ ## Vite+ (recommended)
90
+
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`:
92
+
93
+ ```ts
94
+ import { vitePlusConfig } from '@kirill.konshin/lint/vite-plus';
95
+ import { defineConfig } from 'vite-plus';
96
+
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
+ );
108
+ ```
109
+
110
+ - 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()`
112
+ - 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
+ - `.gitignore` and `.prettierignore` are honoured by Oxfmt; the recommended `.prettierignore` entries are default `fmt.ignorePatterns`, add others there
114
+
115
+ What maps where:
116
+
117
+ <table>
118
+ <thead>
119
+ <tr><th>Before</th><th>Vite+</th></tr>
120
+ </thead>
121
+ <tbody>
122
+ <tr>
123
+ <td>ESLint recommended sets (JS, TS, React, jsx-a11y, Next, import, promise)</td>
124
+ <td>Oxlint <code>correctness</code> category + the same overrides, rule by rule</td>
125
+ </tr>
126
+ <tr>
127
+ <td><code>react-hooks</code></td>
128
+ <td>Oxlint <code>react/*</code> (incl. React Compiler rules)</td>
129
+ </tr>
130
+ <tr>
131
+ <td><code>unused-imports</code></td>
132
+ <td><code>no-unused-vars</code> with import autofix</td>
133
+ </tr>
134
+ <tr>
135
+ <td><code>simple-import-sort</code></td>
136
+ <td>Oxfmt <code>sortImports</code> (same groups)</td>
137
+ </tr>
138
+ <tr>
139
+ <td>Storybook, Tailwind, Turbo, <code>@nx/*</code>, <code>local/test-colocation</code></td>
140
+ <td>Oxlint JS plugins, loaded from this package</td>
141
+ </tr>
142
+ <tr>
143
+ <td>Prettier</td>
144
+ <td>Oxfmt <code>fmt</code> (same options)</td>
145
+ </tr>
146
+ <tr>
147
+ <td>lint-staged</td>
148
+ <td><code>staged</code>: one <code>vp check --fix</code></td>
149
+ </tr>
150
+ <tr>
151
+ <td>Husky</td>
152
+ <td><code>vp config</code> hook dispatcher, <code>.vite-hooks/pre-commit</code></td>
153
+ </tr>
154
+ </tbody>
155
+ </table>
156
+
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`).
158
+
159
+ `package.json`:
160
+
161
+ ```jsonc
162
+ {
163
+ "scripts": {
164
+ "postinstall": "lint-prepare init && vp config", // this order: vp config fills the Vite+ section lint-prepare writes; `prepare` for published roots, see npm-yarn rule
165
+ "lint": "vp check --fix",
166
+ "lint:staged": "vp staged",
167
+ },
168
+ }
169
+ ```
170
+
171
+ WebStorm: the Oxc plugin (`.idea/externalDependencies.xml`, `OxcSettings.xml`, `OxfmtSettings.xml`) with Prettier disabled — templates in the `lint-webstorm` skill.
172
+
173
+ `.vite-hooks/pre-commit`:
174
+
175
+ ```sh
176
+ vp staged
177
+ ```
178
+
179
+ `vp config` installs the hook dispatcher and fills the Vite+ agent instructions into the `<!--VITE PLUS START-->` section `lint-prepare` writes into `AGENTS.md` — so it runs after `lint-prepare` (`vp config` never creates the section itself; `vp migrate --agent` would, but also rewrites dependencies). A `core.hooksPath` left by Husky blocks it: `git config --unset core.hooksPath` once. CI runs `vp check` (no `--fix`).
180
+
181
+ 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`.
71
182
 
72
- ## `.prettierignore`
183
+ ## ESLint + Prettier (without Vite+)
184
+
185
+ ```bash
186
+ $ yarn add -D eslint prettier @kirill.konshin/lint @yarnpkg/types husky lint-staged
187
+ ```
188
+
189
+ ### `.prettierignore`
73
190
 
74
191
  Create `.prettierignore` file:
75
192
 
@@ -88,7 +205,7 @@ https://prettier.io/docs/ignore:
88
205
 
89
206
  > Prettier will also follow rules specified in the ".gitignore" file if it exists in the same directory from which it is run.
90
207
 
91
- ## ESLint
208
+ ### ESLint
92
209
 
93
210
  `eslint.config.mjs`:
94
211
 
@@ -124,7 +241,7 @@ export default defineConfig([
124
241
  ]);
125
242
  ```
126
243
 
127
- ### Full Config Example
244
+ #### Full Config Example
128
245
 
129
246
  Default behavior in the comments, all tools are optional (see [Detection](#detection)). Enable/disable tools using:
130
247
 
@@ -173,24 +290,23 @@ export default defineConfig(
173
290
  );
174
291
  ```
175
292
 
176
- ### Per-package configs (monorepo)
293
+ #### Per-package configs (monorepo)
177
294
 
178
- ESLint 10 resolves the config **per linted file**: the nearest `eslint.config.mjs` up the tree wins **entirely** (no cascading/inheritance of rules). For full per-app Next/Tailwind linting in a multi-app monorepo, give each app its own config — either inherit the root and add overrides:
295
+ ESLint 10 resolves the config **per linted file**: the nearest `eslint.config.mjs` up the tree wins **entirely** (no cascading/inheritance of rules). For full per-app Next/Tailwind linting in a multi-app monorepo, give each app its own config — either inherit the root and add overrides, `apps/web/eslint.config.mjs`:
179
296
 
180
297
  ```js
181
- // apps/web/eslint.config.mjs
182
298
  import { defineConfig } from 'eslint/config';
299
+
183
300
  import rootConfig from '../../eslint.config.mjs';
184
301
 
185
302
  export default defineConfig([...(await rootConfig), { rules: { 'tailwindcss/no-custom-classname': 'off' } }]);
186
303
  ```
187
304
 
188
- …or simply call `defineLintConfig` again with the options this app needs:
305
+ …or simply call `defineLintConfig` again with the options this app needs, `apps/web/eslint.config.mjs`:
189
306
 
190
307
  ```js
191
- // apps/web/eslint.config.mjs
192
- import { defineConfig } from 'eslint/config';
193
308
  import { fileURLToPath } from 'node:url';
309
+ import { defineConfig } from 'eslint/config';
194
310
  import { defineLintConfig } from '@kirill.konshin/lint';
195
311
 
196
312
  export default defineConfig(
@@ -208,7 +324,7 @@ export default defineConfig(
208
324
 
209
325
  The Tailwind block auto-scopes to the **workspace package** owning the entry CSS (emitted as the block's `basePath`), so a single root config doesn't flag class-like strings in non-Tailwind packages; pass `tailwind: { scoped: false }` to apply it workspace-wide (no-op when the entry is owned by the workspace root itself).
210
326
 
211
- ## Prettier `.prettierrc.mjs`:
327
+ ### Prettier `.prettierrc.mjs`
212
328
 
213
329
  ```js
214
330
  import { prettier } from '@kirill.konshin/lint/prettier';
@@ -228,7 +344,9 @@ export default {
228
344
 
229
345
  Import from `/prettier`, not the package root: the root loads every ESLint plugin, which would slow down each Prettier run.
230
346
 
231
- ## Editor Config `.editorconfig`
347
+ ### Editor Config `.editorconfig`
348
+
349
+ Oxfmt reads it too; `fmtConfig()` sets the Prettier behaviors that differ from it.
232
350
 
233
351
  ```editorconfig
234
352
  root = true
@@ -338,6 +456,7 @@ In the project root, `lint-prepare`:
338
456
  - 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.
339
457
  - Mirrors your own top-level entries from `.agents/{rules,skills}/` into `.claude/`. Commands are not synced: make them skills.
340
458
  - 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.
459
+ - 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.
341
460
  - 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.
342
461
 
343
462
  ### OpenSpec
@@ -351,23 +470,73 @@ For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpe
351
470
 
352
471
  Which to reach for:
353
472
 
354
- | Question | Tool | Outcome |
355
- | --- | --- | --- |
356
- | How do I write or change a rule? | `/spec-author` | The specification edited in place, with the code and tests that prove it |
357
- | Do citations resolve, is every new scenario bound, did a rule weaken? | `spec-tools steward check` (the gate, the edit hook) | Fails the merge request on an error |
358
- | Are these the right rules — placement, REQUIRED or ⚠️ ADVISORY, wording, evidence, duplicates, drift across repositories? | the `spec-steward` skill (audit on the `spec-tools` engine, review rounds, align) | A review file of proposals; the owner decides, steward applies; never a build failure |
359
- | Does the code satisfy the intent of the rules, and do the bound tests assert them? | the `spec-verify` skill, run by `spec-tools` | Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI |
360
- | Is the change finished, what did it change, how does CI run the audit? | `spec-tools` (gates, evidence, diff, tier, workers, verdict, comment, html) | Gates and reports for the pipeline |
473
+ <table>
474
+ <thead>
475
+ <tr><th>Question</th><th>Tool</th><th>Outcome</th></tr>
476
+ </thead>
477
+ <tbody>
478
+ <tr>
479
+ <td>How do I write or change a rule?</td>
480
+ <td><code>/spec-author</code></td>
481
+ <td>The specification edited in place, with the code and tests that prove it</td>
482
+ </tr>
483
+ <tr>
484
+ <td>Do citations resolve, is every new scenario bound, did a rule weaken?</td>
485
+ <td><code>spec-tools steward check</code> (the gate, the edit hook)</td>
486
+ <td>Fails the merge request on an error</td>
487
+ </tr>
488
+ <tr>
489
+ <td>Are these the right rules — placement, REQUIRED or ⚠️ ADVISORY, wording, evidence, duplicates, drift across repositories?</td>
490
+ <td>the <code>spec-steward</code> skill (audit on the <code>spec-tools</code> engine, review rounds, align)</td>
491
+ <td>A review file of proposals; the owner decides, steward applies; never a build failure</td>
492
+ </tr>
493
+ <tr>
494
+ <td>Does the code satisfy the intent of the rules, and do the bound tests assert them?</td>
495
+ <td>the <code>spec-verify</code> skill, run by <code>spec-tools</code></td>
496
+ <td>Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI</td>
497
+ </tr>
498
+ <tr>
499
+ <td>Is the change finished, what did it change, how does CI run the audit?</td>
500
+ <td><code>spec-tools</code> (gates, evidence, diff, tier, workers, verdict, comment, html)</td>
501
+ <td>Gates and reports for the pipeline</td>
502
+ </tr>
503
+ </tbody>
504
+ </table>
361
505
 
362
506
  Where each runs:
363
507
 
364
- | What | In CI | Locally |
365
- | --- | --- | --- |
366
- | `spec-tools steward check` | `spec-tools gates`, every merge request: an error fails it | the edit hook on every edit Claude makes, and `spec-tools gates` before handing back |
367
- | `spec-tools steward coverage`, `spec-tools steward evidence --json` | the coverage report, and the evidence `spec-tools scope` builds the spec-verify audit from | on demand |
368
- | spec-steward's corpus audit, review rounds, `align` | never — it is heavy and its outcome is the owner's | on the owner's request: `spec-tools audit --audit spec-steward [--context <decisions file>]`, then the review rounds, where the accepted answers are applied |
369
- | `spec-verify` | one audit job — the reading, then the judging: its verdict gates merge requests and the release | `spec-tools audit`, and `/spec-verify changed` before handing back a spec edit |
370
- | `spec-tools gates`, `evidence`, `diff` | their own jobs | before handing back |
508
+ <table>
509
+ <thead>
510
+ <tr><th>What</th><th>In CI</th><th>Locally</th></tr>
511
+ </thead>
512
+ <tbody>
513
+ <tr>
514
+ <td><code>spec-tools steward check</code></td>
515
+ <td><code>spec-tools gates</code>, every merge request: an error fails it</td>
516
+ <td>the edit hook on every edit Claude makes, and <code>spec-tools gates</code> before handing back</td>
517
+ </tr>
518
+ <tr>
519
+ <td><code>spec-tools steward coverage</code>, <code>spec-tools steward evidence --json</code></td>
520
+ <td>the coverage report, and the evidence <code>spec-tools scope</code> builds the spec-verify audit from</td>
521
+ <td>on demand</td>
522
+ </tr>
523
+ <tr>
524
+ <td>spec-steward's corpus audit, review rounds, <code>align</code></td>
525
+ <td>never — it is heavy and its outcome is the owner's</td>
526
+ <td>on the owner's request: <code>spec-tools audit --audit spec-steward [--context &lt;decisions file&gt;]</code>, then the review rounds, where the accepted answers are applied</td>
527
+ </tr>
528
+ <tr>
529
+ <td><code>spec-verify</code></td>
530
+ <td>one audit job — the reading, then the judging: its verdict gates merge requests and the release</td>
531
+ <td><code>spec-tools audit</code>, and <code>/spec-verify changed</code> before handing back a spec edit</td>
532
+ </tr>
533
+ <tr>
534
+ <td><code>spec-tools gates</code>, <code>evidence</code>, <code>diff</code></td>
535
+ <td>their own jobs</td>
536
+ <td>before handing back</td>
537
+ </tr>
538
+ </tbody>
539
+ </table>
371
540
 
372
541
  Specifications change only by hand, or when the steward skill applies the owner's accepted review answers; `spec-tools steward check --fix` makes the only mechanical repairs. No audit edits code or specifications.
373
542
 
@@ -379,67 +548,15 @@ Setup and the GitLab pipeline are in the `spec-tools` skill.
379
548
 
380
549
  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.
381
550
 
382
- ## Migration
383
-
384
- ### 0.2.x → 0.3.x
385
-
386
- The default-exported config array was replaced by the `defineLintConfig()` factory (see [Settings](#settings)) — every tool integration is auto-detected and controlled via options instead of hand-written blocks.
387
-
388
- Before (0.2.x):
389
-
390
- ```js
391
- import { defineConfig } from 'eslint/config';
392
- import customConfig, { nextPlugin, includeIgnoreFile, tsExts } from '@kirill.konshin/lint';
393
-
394
- export default defineConfig([
395
- ...customConfig,
396
- {
397
- files: [`**/*.${tsExts}`],
398
- plugins: { next: nextPlugin },
399
- settings: { next: { rootDir: 'path/to/next-app' } },
400
- },
401
- { name: 'Custom rules', rules: {} },
402
- includeIgnoreFile(import.meta.url, '.gitignore'),
403
- includeIgnoreFile(import.meta.url, '.prettierignore'),
404
- ]);
405
- ```
406
-
407
- After (0.3.x):
408
-
409
- ```js
410
- import { defineLintConfig } from '@kirill.konshin/lint';
411
-
412
- export default [
413
- ...(await defineLintConfig({
414
- defaultIgnore: { importMetaUrl: import.meta.url },
415
- next: { rootDir: 'path/to/next-app' },
416
- })),
417
- { name: 'Custom rules', rules: {} },
418
- ];
419
- ```
420
-
421
- - **Default export removed** — import `defineLintConfig` and call it. ESLint awaits the returned Promise, so a plain `export default defineLintConfig({...})` works when no extra blocks are needed
422
- - **Manual `settings.next.rootDir` block** → `next: { rootDir }` option — or nothing at all: it is auto-detected from `next.config.*` locations, `package.json`s depending on `next`, and `src/app`/`src/pages` trees (several apps → array)
423
- - **Scans are workspace-root-anchored** — the Tailwind entry / `next.config.*` scans and `nx.json` detection resolve the workspace root via the package manager instead of trusting cwd, so linting from inside a package behaves like linting from the root
424
- - **Manual Tailwind block** (`settings.tailwindcss.cssConfigPath`) → `tailwind: { cssConfigPath }` option; `tailwind: true` without a resolvable entry CSS is now a **hard error** instead of a silent skip, and several entry CSS candidates are a hard error even in auto mode
425
- - **`includeIgnoreFile(import.meta.url, '.gitignore' / '.prettierignore')` pair** → `defaultIgnore: { importMetaUrl: import.meta.url }` (`includeIgnoreFile` stays exported for extra ignore files)
426
- - **`tailwindEntry` const removed** → call the exported `findTailwindEntry(ignores)` when needed
427
- - **New:** every block is a composable exported `*Config()` function; gated ones accept `true` / `false` / an options object with optional `enabled` (defaults to `true` in the object form); `typeAware: true` enables the (slow) type-aware rules
428
- - **`prettier` is now a declared (required) peer dependency** — it was always required by the setup, so no action needed in practice
429
- - **TypeScript consumers get generated declarations** — `LintOptions` and all public exports are typed from source
430
- - **Hoisting** if tools can't find packages, fix it once in the package manager config: keep default hoisting (drop `installConfig.hoistingLimits`/`nohoist`), on pnpm add `public-hoist-pattern[]=<pkg>` to `.npmrc`, or add the tool to root `devDependencies`. Run eslint with `LINT_DEBUG=1` to trace detection.
431
- - **Scans follow the declared workspace.** `scanWorkspace` (also used by all evidence scans) now covers the root directory plus the real `workspaces`/`pnpm-workspace.yaml` packages via `@manypkg/get-packages` instead of a blind ≤5-level glob — config files in directories that are not declared workspace members are only found via the root scan, and the depth limit is gone.
432
- - `has*` probes are anchored at the **workspace root** (via `local-pkg`) instead of this package's install location — identical for standard root installs.
433
-
434
- Everything else — `prettier`, `listStaged`, extension lists (`tsExts`, …), `has*` detection exports, plugin re-exports (`nxPlugin`, …) — is unchanged.
435
-
436
551
  ## Development
437
552
 
438
553
  ### Build
439
554
 
440
- `tsdown` builds two things (`tsdown.config.ts`): the library — ESM and declarations from `src/*.ts`, one file per module, plus the CommonJS Yarn entry from `src/yarn.cts` — into `dist`, and the `spec-tools` CLI — spec-steward included — into one self-contained file, `skills/spec-tools/scripts/cli.js`, which the skills and CI jobs name. `yarn typecheck` (`tsc --noEmit`) checks types; the build does not. Consumers load `dist`, and this monorepo builds lint first in its root `postinstall` before running `lint-prepare`.
555
+ `vp pack` (tsdown, the `pack` block of `vite.config.ts`) builds two things: the library — ESM and declarations from `src/*.ts`, one file per module, plus the CommonJS Yarn entry from `src/yarn.cts` — into `dist`, and the `spec-tools` CLI — spec-steward included — into one self-contained file, `skills/spec-tools/scripts/cli.js`, which the skills and CI jobs name. The root `vp check` checks types (type-aware Oxlint, the TypeScript 7 engine); the build does not. Consumers load `dist`, and this monorepo builds lint first in its root `postinstall` before running `lint-prepare`.
441
556
 
442
- ### Eslint
557
+ ### ESLint and Vite+ configs
558
+
559
+ `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.
443
560
 
444
561
  Declarations are generated from the TypeScript source and retain the underlying package types — `Linter.Config`, Tailwind plugin settings, Prettier `Config`, and lint-staged `Configuration`.
445
562
 
@@ -456,18 +573,60 @@ Due to limitations package visibility between leaf and root this package has to
456
573
  3. **Hoisting, not bridging** — the plugins need the tool's package resolvable from the workspace root; a tool that is evidently in use (2) but not resolvable there (1) is a **hard error** with hoisting guidance (keep default hoisting, pnpm `public-hoist-pattern`, or a root devDependency — see the error text) instead of a silent skip or a cryptic plugin crash. Fix it once in the package manager config; nothing is symlinked at lint time.
457
574
  4. **Yarn Berry PnP** — there is no hoisting to configure; declare the tools at the workspace root as well, keeping versions in sync with the leaves (e.g. the `"vitest": "$vitest"` version-alias hack); `next` documents its own monorepo ESLint setup.
458
575
 
459
- | Option | Package | Evidence glob | When zero / many found |
460
- | --- | --- | --- | --- |
461
- | `tailwind` | `tailwindcss`¹ | `*.css` with `@import "tailwindcss"` | needs exactly **one**: zero → off (forced → error), several → **always** error; set `cssConfigPath` |
462
- | `next` | `next`¹ | `next.config.*`, `package.json` depending on `next`, `src/{app,pages}/` dir | zero → no `rootDir` (optional); many → all as array; or set `rootDir` (the package root, not `src`) |
463
- | `storybook` | `storybook`¹ | `.storybook/main.*` | presence is enough |
464
- | `jest` | `jest`¹ | `jest.config.*` | presence is enough |
465
- | `vitest` | `vitest`¹ | `{vitest,vite}.config.*` | presence is enough |
466
- | `nx` | (plugin bundled) | `nx.json` at the workspace root | — |
467
- | `turbo` | `turbo` | package probe only | — |
576
+ <table>
577
+ <thead>
578
+ <tr><th>Option</th><th>Package</th><th>Evidence glob</th><th>When zero / many found</th></tr>
579
+ </thead>
580
+ <tbody>
581
+ <tr>
582
+ <td><code>tailwind</code></td>
583
+ <td><code>tailwindcss</code>¹</td>
584
+ <td><code>*.css</code> with <code>@import "tailwindcss"</code></td>
585
+ <td>needs exactly <strong>one</strong>: zero → off (forced → error), several → <strong>always</strong> error; set <code>cssConfigPath</code></td>
586
+ </tr>
587
+ <tr>
588
+ <td><code>next</code></td>
589
+ <td><code>next</code>¹</td>
590
+ <td><code>next.config.*</code>, <code>package.json</code> depending on <code>next</code>, <code>src/{app,pages}/</code> dir</td>
591
+ <td>zero → no <code>rootDir</code> (optional); many → all as array; or set <code>rootDir</code> (the package root, not <code>src</code>)</td>
592
+ </tr>
593
+ <tr>
594
+ <td><code>storybook</code></td>
595
+ <td><code>storybook</code>¹</td>
596
+ <td><code>.storybook/main.*</code></td>
597
+ <td>presence is enough</td>
598
+ </tr>
599
+ <tr>
600
+ <td><code>jest</code></td>
601
+ <td><code>jest</code>¹</td>
602
+ <td><code>jest.config.*</code></td>
603
+ <td>presence is enough</td>
604
+ </tr>
605
+ <tr>
606
+ <td><code>vitest</code></td>
607
+ <td><code>vitest</code>¹</td>
608
+ <td><code>{vitest,vite}.config.*</code></td>
609
+ <td>presence is enough</td>
610
+ </tr>
611
+ <tr>
612
+ <td><code>nx</code></td>
613
+ <td>(plugin bundled)</td>
614
+ <td><code>nx.json</code> at the workspace root</td>
615
+ <td>—</td>
616
+ </tr>
617
+ <tr>
618
+ <td><code>turbo</code></td>
619
+ <td><code>turbo</code></td>
620
+ <td>package probe only</td>
621
+ <td>—</td>
622
+ </tr>
623
+ </tbody>
624
+ </table>
468
625
 
469
626
  ¹ 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.
470
627
 
628
+ `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).
629
+
471
630
  The machinery is controlled by the `detection` option (same toggle notation as the tools):
472
631
 
473
632
  - `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (step 2)
@@ -1,4 +1,5 @@
1
1
  import { tsExts } from "../exts.js";
2
+ import { defaultExportFiles } from "../conventions.js";
2
3
  import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
3
4
  import importXPlugin, { createNodeResolver } from "eslint-plugin-import-x";
4
5
  import simpleImportSortPlugin from "eslint-plugin-simple-import-sort";
@@ -33,35 +34,7 @@ function importXConfig() {
33
34
  },
34
35
  {
35
36
  name: "Default export overrides",
36
- files: [
37
- "**/*.config.*",
38
- `**/*.stories.${tsExts}`,
39
- `**/.storybook/main.${tsExts}`,
40
- `**/.storybook/preview.${tsExts}`,
41
- "**/.lintstagedrc*",
42
- "**/.prettierrc*",
43
- `**/App.${tsExts}`,
44
- `**/index.${tsExts}`,
45
- `**/main.${tsExts}`,
46
- "**/*.d.ts",
47
- `**/default.${tsExts}`,
48
- `**/error.${tsExts}`,
49
- `**/forbidden.${tsExts}`,
50
- `**/global-error.${tsExts}`,
51
- `**/layout.${tsExts}`,
52
- `**/loading.${tsExts}`,
53
- `**/not-found.${tsExts}`,
54
- `**/page.${tsExts}`,
55
- `**/template.${tsExts}`,
56
- `**/unauthorized.${tsExts}`,
57
- `**/apple-icon.${tsExts}`,
58
- `**/icon.${tsExts}`,
59
- `**/manifest.${tsExts}`,
60
- `**/opengraph-image.${tsExts}`,
61
- `**/robots.${tsExts}`,
62
- `**/sitemap.${tsExts}`,
63
- `**/twitter-image.${tsExts}`
64
- ],
37
+ files: defaultExportFiles,
65
38
  rules: {
66
39
  "import-x/no-default-export": "off",
67
40
  "@typescript-eslint/naming-convention": "off"
@@ -78,7 +51,7 @@ function importSortConfig() {
78
51
  files: [`**/*.${tsExts}`],
79
52
  plugins: { "simple-import-sort": simpleImportSortPlugin },
80
53
  rules: { "simple-import-sort/imports": ["error", { groups: [
81
- ["^\\u0000.*(polyfill|core-js|regenerator-runtime|whatwg-fetch|@vitest/web-worker)"],
54
+ ["^\\u0000(server-only|client-only)$", "^\\u0000.*(polyfill|core-js|regenerator-runtime|whatwg-fetch|@vitest/web-worker)"],
82
55
  ["^react(-dom)?(/|$)"],
83
56
  ["^node:", "^@?\\w"],
84
57
  ["^@/", "^\\."],
@@ -2,21 +2,6 @@ import { NextOptions } from "../index.js";
2
2
  import { Linter } from "eslint";
3
3
  //#region src/configs/react.d.ts
4
4
  export declare const nextPlugin: typeof import("@next/eslint-plugin-next") | null;
5
- /**
6
- * Auto-find Next.js app roots below the workspace root (scanned like the Tailwind entry - see
7
- * `scanWorkspace`). `next.config.*` is optional in Next.js, so any of three signals marks an app
8
- * root:
9
- * - a `next.config.*` file
10
- * - a `package.json` depending on `next` (see {@link dependsOnNext})
11
- * - a `src/app` or `src/pages` directory - the reported root is the directory CONTAINING `src`,
12
- * because the plugin resolves both layouts (`pages`/`app` and `src/pages`/`src/app`) from the
13
- * package root itself; the bare root-level dir names are too generic to scan for, but such apps
14
- * are caught by the other two signals
15
- *
16
- * Returns absolute directories, deduplicated (one app usually shows several signals) and sorted
17
- * so the emitted settings block is deterministic across filesystems.
18
- */
19
- export declare function findNextRoots(ignores: string[]): string[];
20
5
  /**
21
6
  * Next.js blocks: the whole `eslint-config-next` flat config, plus `settings.next.rootDir`.
22
7
  *
@@ -1,7 +1,6 @@
1
1
  import { tsExts } from "../exts.js";
2
- import { GLOBAL_IGNORES, findWorkspaceRoot, hasNext, scanWorkspace, toolGate } from "../lib.js";
2
+ import { GLOBAL_IGNORES, findNextRoots, findWorkspaceRoot, hasNext, toolGate } from "../lib.js";
3
3
  import { dirname, isAbsolute, join, resolve } from "node:path";
4
- import { readFileSync } from "node:fs";
5
4
  import { globSync } from "glob";
6
5
  import nextTs from "eslint-config-next/typescript";
7
6
  import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
@@ -10,39 +9,6 @@ import reactHooksPlugin from "eslint-plugin-react-hooks";
10
9
  //#region src/configs/react.ts
11
10
  const nextPlugin = hasNext ? (await import("@next/eslint-plugin-next")).default : null;
12
11
  /**
13
- * Does this `package.json` declare `next` as a dependency? Peer/optional declarations are
14
- * deliberately ignored - they mark component libraries, not apps.
15
- */
16
- function dependsOnNext(file) {
17
- try {
18
- const { dependencies, devDependencies } = JSON.parse(readFileSync(file, "utf-8"));
19
- return Boolean(dependencies?.next ?? devDependencies?.next);
20
- } catch {
21
- return false;
22
- }
23
- }
24
- /**
25
- * Auto-find Next.js app roots below the workspace root (scanned like the Tailwind entry - see
26
- * `scanWorkspace`). `next.config.*` is optional in Next.js, so any of three signals marks an app
27
- * root:
28
- * - a `next.config.*` file
29
- * - a `package.json` depending on `next` (see {@link dependsOnNext})
30
- * - a `src/app` or `src/pages` directory - the reported root is the directory CONTAINING `src`,
31
- * because the plugin resolves both layouts (`pages`/`app` and `src/pages`/`src/app`) from the
32
- * package root itself; the bare root-level dir names are too generic to scan for, but such apps
33
- * are caught by the other two signals
34
- *
35
- * Returns absolute directories, deduplicated (one app usually shows several signals) and sorted
36
- * so the emitted settings block is deterministic across filesystems.
37
- */
38
- function findNextRoots(ignores) {
39
- return [.../* @__PURE__ */ new Set([
40
- ...scanWorkspace("next.config.*", ignores).map((file) => dirname(file)),
41
- ...scanWorkspace("package.json", ignores).filter(dependsOnNext).map((file) => dirname(file)),
42
- ...scanWorkspace("src/{app,pages}/", ignores).map((dir) => dirname(dirname(dir)))
43
- ])].sort();
44
- }
45
- /**
46
12
  * Next.js blocks: the whole `eslint-config-next` flat config, plus `settings.next.rootDir`.
47
13
  *
48
14
  * `rootDir` is auto-detected via {@link findNextRoots} when omitted: zero apps found → no settings
@@ -194,4 +160,4 @@ async function reactConfig(option, strict = false) {
194
160
  ];
195
161
  }
196
162
  //#endregion
197
- export { findNextRoots, nextBaseConfig, nextConfig, nextOverridesConfig, nextPlugin, reactBaseConfig, reactConfig, reactSettingsConfig, typescriptOverridesConfig };
163
+ export { nextBaseConfig, nextConfig, nextOverridesConfig, nextPlugin, reactBaseConfig, reactConfig, reactSettingsConfig, typescriptOverridesConfig };
@@ -27,4 +27,14 @@ export declare function findTailwindEntry(ignores: string[]): string | null;
27
27
  *
28
28
  */
29
29
  export declare function tailwindConfig(option?: boolean | TailwindOptions, strict?: boolean): Promise<Linter.Config[]>;
30
+ /**
31
+ * The Tailwind activation decision shared by the ESLint block and the Vite+ config: `null` when off, otherwise the
32
+ * entry CSS (in the consumer's own notation when given) and the absolute directory of the one package to scope the
33
+ * rules to (`null` = the whole workspace).
34
+ */
35
+ export declare function tailwindGate(option?: boolean | TailwindOptions, strict?: boolean): {
36
+ cssConfigPath: string;
37
+ absoluteCssConfigPath: string;
38
+ packageDir: string | null;
39
+ } | null;
30
40
  //#endregion
@@ -46,6 +46,22 @@ function findTailwindEntry(ignores) {
46
46
  *
47
47
  */
48
48
  async function tailwindConfig(option, strict = false) {
49
+ const gate = tailwindGate(option, strict);
50
+ if (!gate) return [];
51
+ const { cssConfigPath, packageDir } = gate;
52
+ const basePath = packageDir ? { basePath: packageDir } : {};
53
+ return [{
54
+ ...(await import("eslint-plugin-tailwindcss")).default.configs.recommended,
55
+ ...basePath,
56
+ settings: { tailwindcss: { cssConfigPath } }
57
+ }];
58
+ }
59
+ /**
60
+ * The Tailwind activation decision shared by the ESLint block and the Vite+ config: `null` when off, otherwise the
61
+ * entry CSS (in the consumer's own notation when given) and the absolute directory of the one package to scope the
62
+ * rules to (`null` = the whole workspace).
63
+ */
64
+ function tailwindGate(option, strict = false) {
49
65
  const { enabled, options, files } = toolGate(option, strict, {
50
66
  tool: "tailwind",
51
67
  has: hasTailwind,
@@ -59,16 +75,16 @@ async function tailwindConfig(option, strict = false) {
59
75
  absolutizeOptions: ({ cssConfigPath }) => cssConfigPath ? [isAbsolute(cssConfigPath) ? cssConfigPath : resolve(findWorkspaceRoot(), cssConfigPath)] : [],
60
76
  scan: () => findTailwindEntries(GLOBAL_IGNORES)
61
77
  });
62
- if (!enabled) return [];
78
+ if (!enabled) return null;
63
79
  const cssConfigPath = options.cssConfigPath ?? files[0];
64
80
  const { scoped = true } = options;
65
- const packageDir = scoped ? packageDirOf(files[0]) : null;
66
- const basePath = packageDir && packageDir !== findWorkspaceRoot() ? { basePath: packageDir } : {};
67
- return [{
68
- ...(await import("eslint-plugin-tailwindcss")).default.configs.recommended,
69
- ...basePath,
70
- settings: { tailwindcss: { cssConfigPath } }
71
- }];
81
+ const owner = scoped ? packageDirOf(files[0]) : null;
82
+ const packageDir = owner && owner !== findWorkspaceRoot() ? owner : null;
83
+ return {
84
+ cssConfigPath,
85
+ absoluteCssConfigPath: files[0],
86
+ packageDir
87
+ };
72
88
  }
73
89
  //#endregion
74
- export { findTailwindEntry, tailwindConfig };
90
+ export { findTailwindEntry, tailwindConfig, tailwindGate };