@kirill.konshin/lint 0.6.8 → 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.
- package/README.md +253 -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 +10 -1
- 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/{rules/electron.md → skills/lint-electron/SKILL.md} +5 -3
- 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 +55 -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/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,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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
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
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
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 <decisions file>]</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`
|
|
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
|
-
###
|
|
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
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
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)
|
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
|
package/dist/configs/tailwind.js
CHANGED
|
@@ -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
|
|
66
|
-
const
|
|
67
|
-
return
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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 };
|