@kirill.konshin/lint 0.6.8 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +255 -94
- package/dist/configs/imports.js +3 -30
- package/dist/configs/react.d.ts +0 -15
- package/dist/configs/react.js +2 -36
- package/dist/configs/tailwind.d.ts +10 -0
- package/dist/configs/tailwind.js +25 -9
- package/dist/configs/testing.js +2 -41
- package/dist/configs/unicorn.js +2 -10
- package/dist/conventions.d.ts +12 -0
- package/dist/conventions.js +53 -0
- package/dist/index.d.ts +4 -4
- package/dist/index.js +4 -4
- package/dist/lib.d.ts +18 -1
- package/dist/lib.js +36 -2
- package/dist/lintPrepare.d.ts +2 -1
- package/dist/lintPrepare.js +13 -1
- package/dist/oxlintPlugin.d.ts +10 -0
- package/dist/oxlintPlugin.js +13 -0
- package/dist/testColocation.d.ts +10 -0
- package/dist/testColocation.js +45 -0
- package/dist/vitePlus.d.ts +58 -0
- package/dist/vitePlus.js +434 -0
- package/package.json +32 -9
- package/rules/agent.md +3 -0
- package/rules/code-style.md +1 -1
- package/rules/github.md +2 -1
- package/rules/gitlab.md +2 -1
- package/rules/jest.md +1 -1
- package/rules/markdown.md +11 -0
- package/rules/monorepo-turbo-nx.md +9 -0
- package/rules/mui.md +0 -2
- package/rules/npm-yarn.md +13 -2
- package/rules/nx.md +3 -2
- package/rules/playwright.md +18 -0
- package/rules/react.md +1 -3
- package/rules/tailwind.md +1 -0
- package/rules/testing.md +5 -2
- package/rules/typescript.md +5 -4
- package/rules/vite.md +5 -1
- package/skills/lint-electron/SKILL.md +80 -0
- package/skills/lint-github/SKILL.md +31 -1
- package/skills/lint-gitlab/SKILL.md +22 -1
- package/skills/lint-migrate/SKILL.md +24 -0
- package/skills/lint-repo/SKILL.md +21 -5
- package/skills/lint-webstorm/SKILL.md +57 -3
- package/skills/spec-steward/SKILL.md +72 -15
- package/skills/spec-steward/references/contract.md +6 -6
- package/skills/spec-tools/SKILL.md +11 -11
- package/skills/spec-tools/references/rules/common.md +32 -7
- package/skills/spec-tools/scripts/cli.js +18 -12
- package/rules/electron.md +0 -25
package/README.md
CHANGED
|
@@ -1,14 +1,20 @@
|
|
|
1
1
|
# @kirill.konshin/lint
|
|
2
2
|
|
|
3
|
-
ESLint + Prettier + lint-staged + Husky
|
|
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
|
|
12
|
+
$ yarn add -D vite-plus @kirill.konshin/lint @yarnpkg/types
|
|
9
13
|
```
|
|
10
14
|
|
|
11
|
-
|
|
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,111 @@ 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
|
+
"build": "vp run -r build", // every workspace package, in dependency order
|
|
168
|
+
"start": "vp run -r --parallel start",
|
|
169
|
+
},
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
WebStorm: the Oxc plugin (`.idea/externalDependencies.xml`, `OxcSettings.xml`, `OxfmtSettings.xml`) with Prettier disabled — templates in the `lint-webstorm` skill.
|
|
174
|
+
|
|
175
|
+
`.vite-hooks/pre-commit`:
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
vp staged
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`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`).
|
|
182
|
+
|
|
183
|
+
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
184
|
|
|
72
|
-
##
|
|
185
|
+
## ESLint + Prettier (without Vite+)
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
$ yarn add -D eslint prettier @kirill.konshin/lint @yarnpkg/types husky lint-staged
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### `.prettierignore`
|
|
73
192
|
|
|
74
193
|
Create `.prettierignore` file:
|
|
75
194
|
|
|
@@ -88,7 +207,7 @@ https://prettier.io/docs/ignore:
|
|
|
88
207
|
|
|
89
208
|
> Prettier will also follow rules specified in the ".gitignore" file if it exists in the same directory from which it is run.
|
|
90
209
|
|
|
91
|
-
|
|
210
|
+
### ESLint
|
|
92
211
|
|
|
93
212
|
`eslint.config.mjs`:
|
|
94
213
|
|
|
@@ -124,7 +243,7 @@ export default defineConfig([
|
|
|
124
243
|
]);
|
|
125
244
|
```
|
|
126
245
|
|
|
127
|
-
|
|
246
|
+
#### Full Config Example
|
|
128
247
|
|
|
129
248
|
Default behavior in the comments, all tools are optional (see [Detection](#detection)). Enable/disable tools using:
|
|
130
249
|
|
|
@@ -173,24 +292,23 @@ export default defineConfig(
|
|
|
173
292
|
);
|
|
174
293
|
```
|
|
175
294
|
|
|
176
|
-
|
|
295
|
+
#### Per-package configs (monorepo)
|
|
177
296
|
|
|
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
|
|
297
|
+
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
298
|
|
|
180
299
|
```js
|
|
181
|
-
// apps/web/eslint.config.mjs
|
|
182
300
|
import { defineConfig } from 'eslint/config';
|
|
301
|
+
|
|
183
302
|
import rootConfig from '../../eslint.config.mjs';
|
|
184
303
|
|
|
185
304
|
export default defineConfig([...(await rootConfig), { rules: { 'tailwindcss/no-custom-classname': 'off' } }]);
|
|
186
305
|
```
|
|
187
306
|
|
|
188
|
-
…or simply call `defineLintConfig` again with the options this app needs
|
|
307
|
+
…or simply call `defineLintConfig` again with the options this app needs, `apps/web/eslint.config.mjs`:
|
|
189
308
|
|
|
190
309
|
```js
|
|
191
|
-
// apps/web/eslint.config.mjs
|
|
192
|
-
import { defineConfig } from 'eslint/config';
|
|
193
310
|
import { fileURLToPath } from 'node:url';
|
|
311
|
+
import { defineConfig } from 'eslint/config';
|
|
194
312
|
import { defineLintConfig } from '@kirill.konshin/lint';
|
|
195
313
|
|
|
196
314
|
export default defineConfig(
|
|
@@ -208,7 +326,7 @@ export default defineConfig(
|
|
|
208
326
|
|
|
209
327
|
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
328
|
|
|
211
|
-
|
|
329
|
+
### Prettier `.prettierrc.mjs`
|
|
212
330
|
|
|
213
331
|
```js
|
|
214
332
|
import { prettier } from '@kirill.konshin/lint/prettier';
|
|
@@ -228,7 +346,9 @@ export default {
|
|
|
228
346
|
|
|
229
347
|
Import from `/prettier`, not the package root: the root loads every ESLint plugin, which would slow down each Prettier run.
|
|
230
348
|
|
|
231
|
-
|
|
349
|
+
### Editor Config `.editorconfig`
|
|
350
|
+
|
|
351
|
+
Oxfmt reads it too; `fmtConfig()` sets the Prettier behaviors that differ from it.
|
|
232
352
|
|
|
233
353
|
```editorconfig
|
|
234
354
|
root = true
|
|
@@ -338,6 +458,7 @@ In the project root, `lint-prepare`:
|
|
|
338
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.
|
|
339
459
|
- Mirrors your own top-level entries from `.agents/{rules,skills}/` into `.claude/`. Commands are not synced: make them skills.
|
|
340
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.
|
|
461
|
+
- 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
462
|
- 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
463
|
|
|
343
464
|
### OpenSpec
|
|
@@ -351,23 +472,73 @@ For a repository specified with [OpenSpec](https://github.com/Fission-AI/OpenSpe
|
|
|
351
472
|
|
|
352
473
|
Which to reach for:
|
|
353
474
|
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
475
|
+
<table>
|
|
476
|
+
<thead>
|
|
477
|
+
<tr><th>Question</th><th>Tool</th><th>Outcome</th></tr>
|
|
478
|
+
</thead>
|
|
479
|
+
<tbody>
|
|
480
|
+
<tr>
|
|
481
|
+
<td>How do I write or change a rule?</td>
|
|
482
|
+
<td><code>/spec-author</code></td>
|
|
483
|
+
<td>The specification edited in place, with the code and tests that prove it</td>
|
|
484
|
+
</tr>
|
|
485
|
+
<tr>
|
|
486
|
+
<td>Do citations resolve, is every new scenario bound, did a rule weaken?</td>
|
|
487
|
+
<td><code>spec-tools steward check</code> (the gate, the edit hook)</td>
|
|
488
|
+
<td>Fails the merge request on an error</td>
|
|
489
|
+
</tr>
|
|
490
|
+
<tr>
|
|
491
|
+
<td>Are these the right rules — placement, REQUIRED or ⚠️ ADVISORY, wording, evidence, duplicates, drift across repositories?</td>
|
|
492
|
+
<td>the <code>spec-steward</code> skill (audit on the <code>spec-tools</code> engine, review rounds, align)</td>
|
|
493
|
+
<td>A review file of proposals; the owner decides, steward applies; never a build failure</td>
|
|
494
|
+
</tr>
|
|
495
|
+
<tr>
|
|
496
|
+
<td>Does the code satisfy the intent of the rules, and do the bound tests assert them?</td>
|
|
497
|
+
<td>the <code>spec-verify</code> skill, run by <code>spec-tools</code></td>
|
|
498
|
+
<td>Graded, quote-proved findings; PASS / FAIL / INCOMPLETE gates CI</td>
|
|
499
|
+
</tr>
|
|
500
|
+
<tr>
|
|
501
|
+
<td>Is the change finished, what did it change, how does CI run the audit?</td>
|
|
502
|
+
<td><code>spec-tools</code> (gates, evidence, diff, tier, workers, verdict, comment, html)</td>
|
|
503
|
+
<td>Gates and reports for the pipeline</td>
|
|
504
|
+
</tr>
|
|
505
|
+
</tbody>
|
|
506
|
+
</table>
|
|
361
507
|
|
|
362
508
|
Where each runs:
|
|
363
509
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
510
|
+
<table>
|
|
511
|
+
<thead>
|
|
512
|
+
<tr><th>What</th><th>In CI</th><th>Locally</th></tr>
|
|
513
|
+
</thead>
|
|
514
|
+
<tbody>
|
|
515
|
+
<tr>
|
|
516
|
+
<td><code>spec-tools steward check</code></td>
|
|
517
|
+
<td><code>spec-tools gates</code>, every merge request: an error fails it</td>
|
|
518
|
+
<td>the edit hook on every edit Claude makes, and <code>spec-tools gates</code> before handing back</td>
|
|
519
|
+
</tr>
|
|
520
|
+
<tr>
|
|
521
|
+
<td><code>spec-tools steward coverage</code>, <code>spec-tools steward evidence --json</code></td>
|
|
522
|
+
<td>the coverage report, and the evidence <code>spec-tools scope</code> builds the spec-verify audit from</td>
|
|
523
|
+
<td>on demand</td>
|
|
524
|
+
</tr>
|
|
525
|
+
<tr>
|
|
526
|
+
<td>spec-steward's corpus audit, review rounds, <code>align</code></td>
|
|
527
|
+
<td>never — it is heavy and its outcome is the owner's</td>
|
|
528
|
+
<td>on the owner's request: <code>spec-tools audit --audit spec-steward [--context <decisions file>]</code>, then the review rounds, where the accepted answers are applied</td>
|
|
529
|
+
</tr>
|
|
530
|
+
<tr>
|
|
531
|
+
<td><code>spec-verify</code></td>
|
|
532
|
+
<td>one audit job — the reading, then the judging: its verdict gates merge requests and the release</td>
|
|
533
|
+
<td><code>spec-tools audit</code>, and <code>/spec-verify changed</code> before handing back a spec edit</td>
|
|
534
|
+
</tr>
|
|
535
|
+
<tr>
|
|
536
|
+
<td><code>spec-tools gates</code>, <code>evidence</code>, <code>diff</code></td>
|
|
537
|
+
<td>their own jobs</td>
|
|
538
|
+
<td>before handing back</td>
|
|
539
|
+
</tr>
|
|
540
|
+
</tbody>
|
|
541
|
+
</table>
|
|
371
542
|
|
|
372
543
|
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
544
|
|
|
@@ -379,67 +550,15 @@ Setup and the GitLab pipeline are in the `spec-tools` skill.
|
|
|
379
550
|
|
|
380
551
|
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
552
|
|
|
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
553
|
## Development
|
|
437
554
|
|
|
438
555
|
### Build
|
|
439
556
|
|
|
440
|
-
`tsdown`
|
|
557
|
+
`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
558
|
|
|
442
|
-
###
|
|
559
|
+
### ESLint and Vite+ configs
|
|
560
|
+
|
|
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.
|
|
443
562
|
|
|
444
563
|
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
564
|
|
|
@@ -456,18 +575,60 @@ Due to limitations package visibility between leaf and root this package has to
|
|
|
456
575
|
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
576
|
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
577
|
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
578
|
+
<table>
|
|
579
|
+
<thead>
|
|
580
|
+
<tr><th>Option</th><th>Package</th><th>Evidence glob</th><th>When zero / many found</th></tr>
|
|
581
|
+
</thead>
|
|
582
|
+
<tbody>
|
|
583
|
+
<tr>
|
|
584
|
+
<td><code>tailwind</code></td>
|
|
585
|
+
<td><code>tailwindcss</code>¹</td>
|
|
586
|
+
<td><code>*.css</code> with <code>@import "tailwindcss"</code></td>
|
|
587
|
+
<td>needs exactly <strong>one</strong>: zero → off (forced → error), several → <strong>always</strong> error; set <code>cssConfigPath</code></td>
|
|
588
|
+
</tr>
|
|
589
|
+
<tr>
|
|
590
|
+
<td><code>next</code></td>
|
|
591
|
+
<td><code>next</code>¹</td>
|
|
592
|
+
<td><code>next.config.*</code>, <code>package.json</code> depending on <code>next</code>, <code>src/{app,pages}/</code> dir</td>
|
|
593
|
+
<td>zero → no <code>rootDir</code> (optional); many → all as array; or set <code>rootDir</code> (the package root, not <code>src</code>)</td>
|
|
594
|
+
</tr>
|
|
595
|
+
<tr>
|
|
596
|
+
<td><code>storybook</code></td>
|
|
597
|
+
<td><code>storybook</code>¹</td>
|
|
598
|
+
<td><code>.storybook/main.*</code></td>
|
|
599
|
+
<td>presence is enough</td>
|
|
600
|
+
</tr>
|
|
601
|
+
<tr>
|
|
602
|
+
<td><code>jest</code></td>
|
|
603
|
+
<td><code>jest</code>¹</td>
|
|
604
|
+
<td><code>jest.config.*</code></td>
|
|
605
|
+
<td>presence is enough</td>
|
|
606
|
+
</tr>
|
|
607
|
+
<tr>
|
|
608
|
+
<td><code>vitest</code></td>
|
|
609
|
+
<td><code>vitest</code>¹</td>
|
|
610
|
+
<td><code>{vitest,vite}.config.*</code></td>
|
|
611
|
+
<td>presence is enough</td>
|
|
612
|
+
</tr>
|
|
613
|
+
<tr>
|
|
614
|
+
<td><code>nx</code></td>
|
|
615
|
+
<td>(plugin bundled)</td>
|
|
616
|
+
<td><code>nx.json</code> at the workspace root</td>
|
|
617
|
+
<td>—</td>
|
|
618
|
+
</tr>
|
|
619
|
+
<tr>
|
|
620
|
+
<td><code>turbo</code></td>
|
|
621
|
+
<td><code>turbo</code></td>
|
|
622
|
+
<td>package probe only</td>
|
|
623
|
+
<td>—</td>
|
|
624
|
+
</tr>
|
|
625
|
+
</tbody>
|
|
626
|
+
</table>
|
|
468
627
|
|
|
469
628
|
¹ 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
629
|
|
|
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).
|
|
631
|
+
|
|
471
632
|
The machinery is controlled by the `detection` option (same toggle notation as the tools):
|
|
472
633
|
|
|
473
634
|
- `detection: false` — tools are OFF unless explicitly enabled; enabled tools still auto-detect their settings (step 2)
|
package/dist/configs/imports.js
CHANGED
|
@@ -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
|
["^@/", "^\\."],
|
package/dist/configs/react.d.ts
CHANGED
|
@@ -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
|
*
|
package/dist/configs/react.js
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
import { tsExts } from "../exts.js";
|
|
2
|
-
import { GLOBAL_IGNORES, findWorkspaceRoot, hasNext,
|
|
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 {
|
|
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
|