@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.
Files changed (51) hide show
  1. package/README.md +255 -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 +2 -1
  27. package/rules/gitlab.md +2 -1
  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 +13 -2
  33. package/rules/nx.md +3 -2
  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/skills/lint-electron/SKILL.md +80 -0
  41. package/skills/lint-github/SKILL.md +31 -1
  42. package/skills/lint-gitlab/SKILL.md +22 -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 +57 -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
  51. package/rules/electron.md +0 -25
package/rules/nx.md CHANGED
@@ -10,10 +10,11 @@ paths:
10
10
  # NX
11
11
 
12
12
  - If NX is used root `package.json` must have `nx show projects > /dev/null` in the `prepare`/`postinstall` script, so the project graph cache exists for tools that read it outside `nx` — e.g. `@nx/eslint-plugin` rules in a bare `eslint` run silently skip without it. With `prepare`, Yarn 2+ skips it on install — run `yarn prepare` explicitly (after cloning + as a CI step); with `postinstall` (private root) Yarn runs it on install, so no extra step
13
- - Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see `github.md` / `gitlab.md`). One cache entry holds one DB, so restoring several entries does not merge their outputs.
13
+ - With Nx Cloud (`nxCloudId` in `nx.json`) the remote cache replaces CI caching of `.nx/cache` — do NOT cache `.nx` in CI. Set Workspace visibility → Organization members only in the Nx Cloud workspace settings (no anonymous access; fork PRs run without the cache); developers run `npx nx login` once (personal read-write token in the home folder, no env var); CI passes `NX_CLOUD_ACCESS_TOKEN` from repository secrets (environment secrets reach only jobs that declare the environment): a read-write CI access token only on protected branches (`main`, release), a read-only CI access token everywhere else
14
+ - Without Nx Cloud: Nx 20+ indexes `.nx/cache` in a SQLite DB in `.nx/workspace-data`, named after the machine ID. A CI cache must carry both, with the DB under the fixed name `default-v*.db`: rename it to the machine ID before install and back before saving (see `github.md` / `gitlab.md`). One cache entry holds one DB, so restoring several entries does not merge their outputs.
14
15
  - NX Release (v23+) with conventional commits silently demotes bumps for `0.x` packages (breaking → minor, `feat` → patch) while the log still claims `Applied semver relative bump "minor"`;
15
16
  - set `release.version.adjustSemverBumpsForZeroMajorVersion: false` in `nx.json` if `feat:` must bump minor before `1.0.0`
16
- - Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with concurrency flags set once here;
17
+ - Root NX task-script convention: bare name = `nx run-many -t <target>` over all projects (`build`/`test`/`start`/`serve`), with NO `--parallel` flags: parallelism lives in the root `.env` (`NX_PARALLEL=50%` — Nx loads it before every command and parses percentages; `nx.json` `parallel` takes only a number, a string there dispatches nothing); continuous tasks (`start`) always all run, each in its own slot; test runners limit their own workers (Vitest `maxWorkers: '50%'`);
17
18
  - Add a NX scripts to root `package.json`:
18
19
  - `<target>:packages` scopes to publishable libs (`yarn <target> --projects '@scope/*'`);
19
20
  - `<target>:affected` = `nx affected -t <target>` for CI (exclude demos, diff vs `origin/main`)
@@ -0,0 +1,18 @@
1
+ ---
2
+ type: always_apply
3
+ description: Set of rules for projects with Playwright
4
+ paths:
5
+ - '**/playwright.config.{ts,js,mjs,cjs}'
6
+ - '**/e2e/**'
7
+ ---
8
+
9
+ - The apps under test are started outside Playwright, never by its `webServer`: the e2e target `dependsOn` the continuous `start` / `dev` / `serve` targets plus their `wait` probes (`wait-on`), or Docker Compose runs the stack and the suite as a service; see monorepo-turbo-nx.md
10
+ - The suite reaches the apps through `baseURL` (and other URLs) from the environment, so the same specs run locally, in Compose and against a deployment
11
+ - E2E targets against running apps are `cache: false`; reports and traces (`test-results`, `playwright-report`) are their outputs and CI artifacts
12
+ - How Playwright splits the work:
13
+ - `workers` — parallel worker processes on one machine (default: half of the cores)
14
+ - test files run in parallel across workers; tests inside a file run in order unless `fullyParallel: true` (or `test.describe.configure({ mode: 'parallel' })`)
15
+ - `projects` — every project (browser, runtime, device) runs the matching specs again
16
+ - `--shard=<i>/<n>` — splits the suite across CI machines; merge the `blob` reports with `playwright merge-reports`
17
+ - Run serially (`workers: 1`, `fullyParallel: false`) when tests share external state — accounts, sessions, a stopped service, a stateful backend; say why in the config
18
+ - On CI: `forbidOnly`, `retries`, trace / video `on-first-retry`, screenshots `only-on-failure`, a JUnit report for the CI test widget and an HTML report as an artifact
package/rules/react.md CHANGED
@@ -23,9 +23,7 @@ paths:
23
23
 
24
24
  ```tsx
25
25
  import { FC, memo } from 'react';
26
- export type CmpProps = {
27
- /* types */
28
- }; // or never if no props needed
26
+ export type CmpProps = {/* types */}; // or never if no props needed
29
27
  export const Cmp: FC<CmpProps> = memo(function Cmp(props) {
30
28
  /* code */
31
29
  });
package/rules/tailwind.md CHANGED
@@ -34,6 +34,7 @@ description: Set of rules for projects which use Tailwind
34
34
 
35
35
  # ESLint (eslint-plugin-tailwindcss, bundled with @kirill.konshin/lint)
36
36
 
37
+ - With Vite+ the same plugin runs as an Oxlint JS plugin with the same detection; pass `tailwind: { cssConfigPath }` as `vitePlusConfig` options instead of `eslint.config.mjs`
37
38
  - The plugin MUST be able to resolve the Tailwind entry CSS or it hard-crashes lint (ENOENT)
38
39
  - Zero-config happy path: when the workspace contains exactly ONE `*.css` with `@import "tailwindcss"` (scanned across the root + every workspace package, `.gitignore`-aware), rules auto-enable with that entry
39
40
  - Rules auto-scope to the workspace package owning the entry CSS (block `basePath`); pass `tailwind: { scoped: false }` to lint the whole workspace
package/rules/testing.md CHANGED
@@ -5,13 +5,16 @@ paths:
5
5
  - '**/jest.config.{ts,js,mjs,cjs}'
6
6
  - '**/vite.config.{ts,js,mjs,cjs}'
7
7
  - '**/vitest.config.{ts,js,mjs,cjs}'
8
+ - '**/vitest.*.config.{ts,js,mjs,cjs}'
8
9
  - '**/*.test.*'
9
10
  - '**/*.spec.*'
10
11
  - '**/*.fixture.*'
11
12
  ---
12
13
 
13
- - If project use `vite` use `vitest`, otherwise `jest`
14
- - If project needs browser-based testing use `playwright`
14
+ - If project use `vite` or `vite-plus` use `vitest` (`vp test`, imports from `vite-plus/test`), otherwise `jest`
15
+ - With Nx / Turbo, CI runs tests through the orchestrator and its cache (full and affected); the test tool at the root over all projects (`vp test` with `test.projects`, `maxWorkers: '100%'`) is the local full-speed run (see monorepo-turbo-nx.md)
16
+ - If project needs browser-based testing use `playwright`; it splits work over worker processes, test files and `--shard`s (see playwright.md)
17
+ - Suites that need a real server (integration, e2e — Vitest / Jest too): a separate test config and target (e.g. `test:integration` with `vitest.integration.config.ts` over `*.spec.ts`), started by the orchestrator — `dependsOn` the continuous `dev` / `start` plus a `wait` probe, `cache: false` — with a JUnit report; a CI job against an external environment may be allowed to fail, and is not created where its credentials are missing
15
18
  - Naming
16
19
  - `*.test.ts` for unit tests
17
20
  - `*.spec.ts` for e2e or integration tests (require running DEV server)
@@ -11,7 +11,8 @@ paths:
11
11
 
12
12
  - ALL projects must use TypeScript by default
13
13
  - JavaScript is acceptable for service scripts, but discouraged, use `ts-node`
14
- - Do NOT upgrade to TypeScript 7 until `typescript-eslint` supports it
14
+ - Do NOT upgrade to TypeScript 7 while tools load the TypeScript JS API (typescript-eslint, ctix, `@arethetypeswrong/core`, Storybook docgen, Next.js type checks, `spec-tools`): TS 7 ships only an unstable API; use its engine through Vite+ type-aware checks
15
+ - With Vite+ (`vite-plus` installed) type-check with `vp check` (`vitePlusConfig` has `typeAware` on by default, the TypeScript 7 engine via tsgolint); NEVER add `tsc --noEmit` scripts; without Vite+ use `tsc --noEmit`
15
16
  - ALL configs should use TypeScript if possible via `defineConfig` or at least import TS type for configuration.
16
17
  - Prefer short-circuit evaluation and early exit
17
18
  - Use structured logging with context, consider adding function arguments to log:
@@ -72,8 +73,8 @@ paths:
72
73
  - Import siblings directly `./file.ts`
73
74
  - Do not import more than one level up: `../file` OK, but not preferred
74
75
  - NOT OK: more than one level `../../file` or stepping aside from parent dir `../dir/file`
75
- - Order imports in this sequence, one blank line between groups (enforced and autofixed by `simple-import-sort`):
76
- 1. Polyfills — side-effect imports that must run first (`core-js`, `regenerator-runtime`, `whatwg-fetch`, `@vitest/web-worker`)
76
+ - Order imports in this sequence, one blank line between groups (autofixed by Oxfmt `sortImports` with Vite+, `simple-import-sort` otherwise):
77
+ 1. Polyfills and guards — side-effect imports that must run first (`server-only`, `client-only`, `core-js`, `regenerator-runtime`, `whatwg-fetch`, `@vitest/web-worker`)
77
78
  2. React (`react`, `react-dom`)
78
79
  3. Third-party library imports (other packages, incl. `node:` builtins)
79
80
  4. Local imports (path aliases `@/...`, then relative `./`, `../`)
@@ -92,7 +93,7 @@ paths:
92
93
  # Type Annotation Patterns
93
94
 
94
95
  - Use `interface` only for declaration merging/augmentation (e.g. extending a third-party global interface) - a class can `implements` a `type` alias just as well, so that's not a reason to reach for `interface`
95
- - This is enforced by lint (`@typescript-eslint/consistent-type-definitions`), which can't special-case augmentation - when it's genuinely needed, add `// eslint-disable-next-line @typescript-eslint/consistent-type-definitions` above the `interface`
96
+ - This is enforced by lint (`@typescript-eslint/consistent-type-definitions`), which can't special-case augmentation - when it's genuinely needed, add `// oxlint-disable-next-line typescript/consistent-type-definitions` (Vite+) or `// eslint-disable-next-line @typescript-eslint/consistent-type-definitions` above the `interface`
96
97
  - Prefer to inline types into function signature or variable declarations
97
98
  - Introduce types when reused or complex. Avoid creating a type for every single thing
98
99
  - Try to reuse types that exist in project (e.g. redux state, zod schema, component props, final function signature can have one shared type + derivatives like `Omit<>`, `Partial<>` etc.)
package/rules/vite.md CHANGED
@@ -3,17 +3,21 @@ type: always_apply
3
3
  description: Set of rules for projects with Vite
4
4
  paths:
5
5
  - '**/vite.config.ts'
6
+ - '**/vitest.config.ts'
6
7
  ---
7
8
 
9
+ - Prefer [Vite+](https://viteplus.dev) (`vite-plus`, `vp` CLI): `defineConfig` from `vite-plus`, root config from `vitePlusConfig` (`@kirill.konshin/lint/vite-plus`), see the package README
10
+ - Libraries build with `vp pack` (`pack` block, tsdown), apps with `vp build`, tests run with `vp test` and import from `vite-plus/test`
11
+ - Keep `lint`/`fmt` in the root config only; per-package settings go to `lint.overrides`/`fmt.overrides`
8
12
  - Web Worker Polyfill `import '@vitest/web-worker';`
9
13
  - In monorepo define root vitest project https://vitest.dev/guide/projects.html#defining-projects
10
14
 
11
15
  # Prefer the shortest possible config definition
12
16
 
13
17
  ```ts
14
- import { defineConfig } from 'vite';
15
18
  import tailwindcss from '@tailwindcss/vite';
16
19
  import react from '@vitejs/plugin-react';
20
+ import { defineConfig } from 'vite-plus';
17
21
 
18
22
  export default defineConfig({
19
23
  plugins: [react(), tailwindcss()],
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: lint-electron
3
+ description: Skill for Electron-based apps - dev runner that restarts Electron (vp pack --watch), packaging a Next.js standalone server with electron-builder in a hoisted monorepo, CI builds. Use when setting up, running or packaging an Electron app.
4
+ ---
5
+
6
+ # Dev Runner
7
+
8
+ ALWAYS run the main process in development with `vp pack --watch` (Vite+, tsdown), never `tsc-watch`, `nodemon` or `electron .` alone: it rebuilds the entrypoint and restarts Electron through `onSuccess` (tsdown stops the previous process). Files outside the main process module graph that need a restart (`next.config.*`: Next.js applies config only on a restart, like `next dev`; a linked library build) go in through a plugin — the `watch` option cannot list them, `--watch` overrides it with `true`:
9
+
10
+ ```ts
11
+ import path from 'node:path';
12
+
13
+ import { defineConfig } from 'vite-plus';
14
+
15
+ const isWatch = process.argv.includes('--watch');
16
+
17
+ // absolute: Rolldown's `addWatchFile` takes them as is
18
+ const restartOn = ['next.config.ts'].map((file) => path.resolve(import.meta.dirname, file));
19
+
20
+ export default defineConfig({
21
+ pack: {
22
+ entry: ['src-electron/index.ts'],
23
+ outDir: 'build',
24
+ format: 'esm',
25
+ platform: 'node',
26
+ fixedExtension: false,
27
+ dts: false,
28
+ deps: { neverBundle: true },
29
+ tsconfig: 'tsconfig-electron.json',
30
+ ...(isWatch && {
31
+ plugins: [
32
+ {
33
+ name: 'restart-on',
34
+ buildStart() {
35
+ for (const file of restartOn) this.addWatchFile(file);
36
+ },
37
+ },
38
+ ],
39
+ onSuccess: 'cross-env NODE_ENV=development electron .',
40
+ }),
41
+ },
42
+ });
43
+ ```
44
+
45
+ Scripts: `"start": "vp pack --watch"`, `"build:main": "vp pack"`.
46
+
47
+ # Packaging a Next.js Standalone Server
48
+
49
+ In a hoisted workspace (see npm-yarn rule) Next.js traces the server's dependencies into `.next/standalone/node_modules`, beside the app folder; package both, without Electron:
50
+
51
+ ```yaml
52
+ files:
53
+ - build
54
+ - '.next/standalone/<app>/**/*'
55
+ - '.next/standalone/node_modules/**/*'
56
+ - '!.next/standalone/node_modules/electron'
57
+ ```
58
+
59
+ # CI Builds
60
+
61
+ ## Gitlab
62
+
63
+ ```yml
64
+ variables:
65
+ USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
66
+
67
+ build:
68
+ image: macos-12-xcode-13 # not exact version, but the point is to use macos-compatible image
69
+ tags:
70
+ - shared-macos-amd64
71
+ script:
72
+ - yarn --immutable
73
+ - yarn build
74
+ - rm -rf electron/dist/mac # some cleanup to make artifacts leaner
75
+ only:
76
+ - master
77
+ artifacts:
78
+ paths:
79
+ - electron/dist
80
+ ```
@@ -5,6 +5,30 @@ description: Describes how to work with Github & example workflow as a reference
5
5
 
6
6
  Reference CI: two local composite actions and a workflow. Checks run as parallel jobs; publishing needs all of them.
7
7
 
8
+ # With Nx Cloud (`nxCloudId` in `nx.json`)
9
+
10
+ The remote cache replaces the local Nx cache. Take the templates below without the `nx-cache` action: no `Restore Nx cache` step and `nx-cache` input in `setup`, no `Save Nx cache` steps and `nx-cache:` inputs in workflows.
11
+
12
+ - Nx Cloud workspace settings: Workspace visibility → Organization members only (fork PRs run without the cache); create two CI access tokens, read-write and read-only
13
+ - GitHub **repository** secrets — environment secrets reach only jobs that declare the environment, and every Nx job needs the token: `NX_CLOUD_ACCESS_TOKEN` (read-write), `NX_CLOUD_ACCESS_TOKEN_READ_ONLY`
14
+ - Developers: `npx nx login` once per machine
15
+
16
+ Workflow running only on `main` (release):
17
+
18
+ ```yml
19
+ env:
20
+ NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
21
+ ```
22
+
23
+ PR workflow (fork PRs get no secrets and run without the cache):
24
+
25
+ ```yml
26
+ env:
27
+ NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN_READ_ONLY }}
28
+ ```
29
+
30
+ # Without Nx Cloud
31
+
8
32
  `.github/actions/nx-cache/action.yml` — Nx 20+ ignores a restored `.nx/cache` without its DB:
9
33
 
10
34
  ```yml
@@ -166,6 +190,8 @@ jobs:
166
190
  lint:
167
191
  name: Lint
168
192
  runs-on: ubuntu-latest
193
+ # type checks read the built declarations; after the build job its build is all cache hits
194
+ needs: build
169
195
 
170
196
  steps:
171
197
  - name: Checkout Repo
@@ -176,8 +202,12 @@ jobs:
176
202
  with:
177
203
  nx-cache: build # reuses the build job's cache; this job does not save
178
204
 
205
+ # type checks read the built declarations of workspace packages
206
+ - name: Build packages
207
+ run: yarn build # the orchestrator, cache hits
208
+
179
209
  - name: Lint
180
- run: yarn lint
210
+ run: yarn vp check # Vite+: format + lint + type checks, no --fix; without Vite+: yarn lint
181
211
 
182
212
  test:
183
213
  name: Test
@@ -3,6 +3,26 @@ name: lint-gitlab
3
3
  description: Describes how to work with Gitlab Pipelines & example pipeline as a reference which essential jobs and concepts usual Gitlab project should have
4
4
  ---
5
5
 
6
+ # With Nx Cloud (`nxCloudId` in `nx.json`)
7
+
8
+ The remote cache replaces the local Nx cache. Take the pipeline below without the `.nx/cache` and `.nx/workspace-data/default-v*.db` cache paths and without the Nx DB steps in `before_script` / `after_script`.
9
+
10
+ - Nx Cloud workspace settings: Workspace visibility → Organization members only (pipelines without a token run without the cache); create two CI access tokens, read-write and read-only
11
+ - CI/CD variables, masked: `NX_CLOUD_ACCESS_TOKEN` (read-write, **protected** — protected branches only), `NX_CLOUD_ACCESS_TOKEN_READ_ONLY` (not protected)
12
+ - Developers: `npx nx login` once per machine
13
+
14
+ ```yml
15
+ workflow:
16
+ rules:
17
+ # merge requests read the remote cache only
18
+ - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
19
+ variables:
20
+ NX_CLOUD_ACCESS_TOKEN: $NX_CLOUD_ACCESS_TOKEN_READ_ONLY
21
+ - when: always
22
+ ```
23
+
24
+ # Without Nx Cloud
25
+
6
26
  ```yml
7
27
  image: node:lts
8
28
 
@@ -72,7 +92,8 @@ install:
72
92
  lint:
73
93
  stage: test
74
94
  script:
75
- - yarn lint
95
+ - yarn build # type checks read the built declarations of workspace packages; the orchestrator, cache hits
96
+ - yarn vp check # Vite+: format + lint + type checks, no --fix; without Vite+: yarn lint
76
97
 
77
98
  test:
78
99
  stage: test
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: lint-migrate
3
+ description: Upgrade a project that uses @kirill.konshin/lint to a newer minor version - one section per version step (0.6 -> 0.7 moves ESLint + Prettier + lint-staged + Husky to Vite+). Use when upgrading @kirill.konshin/lint, or when asked to move a repo to Vite+ / Oxlint / Oxfmt.
4
+ ---
5
+
6
+ # Lint Migrate
7
+
8
+ Only what changes between versions; the target setup is the package README (`node_modules/@kirill.konshin/lint/README.md`).
9
+
10
+ 1. Check `git status`; ask the user to commit unrelated work
11
+ 2. Apply each section from the installed version up to the target, in order; reconcile, never overwrite project settings
12
+ 3. Run the `lint-repo` skill: set up / update tooling (checks every file against the README), then its audit
13
+
14
+ # 0.6 -> 0.7
15
+
16
+ 0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+ or the project uses Yarn PnP.
17
+
18
+ - **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
19
+ - **Set up** Vite+ by hand per the README "Vite+" section — not `vp migrate`: it copies every expanded ESLint rule, writes absolute paths and broken regexes, and rewrites dependencies; if it was run, replace its `lint` / `fmt` blocks with `vitePlusConfig`
20
+ - **Carry over**: rules from `eslint.config.*` → `lint.rules` / `lint.overrides` (`@typescript-eslint/x` → `typescript/x`, `react-hooks/x` → `react/x`, `import-x/x` → `import/x`, `@nx/*` unchanged); extra `.prettierignore` entries → `fmt.ignorePatterns`; root `vitest.config.*` → the `test` block
21
+ - **Remove**: `eslint.config.*`, `.prettierrc*`, `.prettierignore`, `.lintstagedrc*`, `vitest.config.*`, `tsdown.config.*` (→ `pack`), `.husky/` (→ `.vite-hooks/`; `git config --unset core.hooksPath`); dependencies `prettier`, `lint-staged`, `husky`, `vitest`, `tsdown`, `vite-plugin-dts`, `rollup-preserve-directives` — keep `eslint` only for `@nx/eslint-plugin`
22
+ - **Rewrite**: `from 'vitest'` → `from 'vite-plus/test'` (keep `declare module 'vitest'`); `defineConfig` from `vite-plus`; library `vite build` with `preserveModules` → `pack` with `unbundle: true`, `dts: true`, `deps: { neverBundle: true }`; inline disables of file-name rules → `lint.overrides`
23
+ - **Expect**: a one-time Oxfmt reformat (commit as `style:` / `chore:`); type errors the old setup never reported (`typeAware` is on), TS 7-removed tsconfig options (`target: es5`, `moduleResolution: node`, `downlevelIteration`) and TS 6's empty default `types` (list `["node", "vite-plus/client"]`); new Oxlint findings are real — fix, or override with a reason; `@nx/dependency-checks` is gone (Oxlint lints no JSON)
24
+ - **Verify**: every package's build and tests; `dist` file lists and `package.json` `exports` unchanged
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-repo
3
- description: Set up/update this repo's ESLint + Prettier + lint-staged + Husky tooling (@kirill.konshin/lint), and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
3
+ description: Set up/update this repo's lint/format/pre-commit tooling (@kirill.konshin/lint) - Vite+ (Oxlint, Oxfmt, vp staged/hooks) by default, ESLint + Prettier + lint-staged + Husky when Vite+ is not used, and/or audit the codebase against the packaged agent rules. Rules are discovered from .agents/rules/*.md (created by `lint-prepare init`), falling back to node_modules/@kirill.konshin/lint/rules/*.md; project overrides in AGENTS.md Custom Rules / CLAUDE.md win on conflict. Use when asked to set up, configure, or upgrade lint/format/pre-commit tooling, OR to check, audit, verify, or lint the codebase against agent rules/conventions.
4
4
  ---
5
5
 
6
6
  # Lint Repo
@@ -14,7 +14,23 @@ Full config templates: `node_modules/@kirill.konshin/lint/README.md`
14
14
 
15
15
  ## A. Set up / update tooling
16
16
 
17
- Follow `node_modules/@kirill.konshin/lint/README.md`, reconciling (never blindly overwriting project-specific overrides). When **upgrading** `@kirill.konshin/lint` from an older version, first apply the README's "Migration" section (e.g. 0.2.x → 0.3.x: default-exported array → `defineLintConfig()` options):
17
+ Follow `node_modules/@kirill.konshin/lint/README.md`, reconciling (never blindly overwriting project-specific overrides). When **upgrading** `@kirill.konshin/lint` from an older version, first apply the `lint-migrate` skill.
18
+
19
+ Vite+ is the default. Use the ESLint + Prettier flow only when the user declines Vite+ or the project cannot run it (Yarn PnP).
20
+
21
+ ### Vite+
22
+
23
+ Write the config by hand. `vp migrate` is only an optional first pass: it copies every expanded ESLint rule, absolute paths and broken regexes into `vite.config.ts`, so clean up after it as `lint-migrate` describes.
24
+
25
+ 1. **Install** — add `vite-plus`, `@kirill.konshin/lint` (+ `eslint` only for Nx module-boundary rules); pin `vite`/`vitest` at the root (README "Yarn constraints").
26
+ 2. **Config** — root `vite.config.ts`: `defineConfig(vitePlusConfig({ ...project blocks }, { ...toggles }))`; move project rule overrides into `lint.rules` / `lint.overrides`, ignores into `ignorePatterns`. Keep `.editorconfig`.
27
+ 3. **Hooks** — `lint-prepare init && vp config` in `prepare`/`postinstall` — in this order: `vp config` fills the Vite+ section `lint-prepare` writes into `AGENTS.md` (same choice as below), `.vite-hooks/pre-commit` with `vp staged`; scripts `lint: vp check --fix`, `lint:staged: vp staged`; workspace-wide scripts move from `yarn workspaces foreach` to `vp run -r` (npm-yarn rule).
28
+ 4. **Tests/builds** — tests import from `vite-plus/test`; libraries `vp pack`, apps `vp build`.
29
+ 5. **CI** — `vp check` (no `--fix`), see `lint-github` / `lint-gitlab`.
30
+ 6. **IDEA** — apply `lint-webstorm` if the repo has a JetBrains `.idea`.
31
+ 7. **Install** — run the package manager; then `vp check` and the tests.
32
+
33
+ ### ESLint + Prettier
18
34
 
19
35
  1. **Install** — add `eslint`, `prettier`, `@kirill.konshin/lint`, `husky`, `lint-staged` (+ the PNPM `.npmrc` block if pnpm).
20
36
  2. **Config** — create/reconcile `.editorconfig`, `eslint.config.mjs` and `.prettierrc.mjs` (pass `defineLintConfig` options as needed — e.g. `defaultIgnore: { importMetaUrl: import.meta.url }`, `next: { rootDir }` — and keep project rule overrides).
@@ -31,7 +47,7 @@ Rules: `.agents/rules/*.md` → else `node_modules/@kirill.konshin/lint/rules/*.
31
47
 
32
48
  ### 1. Mechanical pass first
33
49
 
34
- Run `eslint .` and `prettier --check .` **without `--fix`**. Report compactly (counts + notable files). Ask: fix all / pick / skip. Apply the confirmed fixes (`eslint --fix`, `prettier --write`). This cleans deterministic issues so the rule audit runs on a patched tree.
50
+ Run `vp check` (Vite+) or `eslint .` and `prettier --check .` **without `--fix`**. Report compactly (counts + notable files). Ask: fix all / pick / skip. Apply the confirmed fixes (`vp check --fix`, or `eslint --fix` and `prettier --write`). This cleans deterministic issues so the rule audit runs on a patched tree.
35
51
 
36
52
  ### 2. Rule audit
37
53
 
@@ -49,9 +65,9 @@ Go one-by-one / reply with instructions / skip all / fix all. Do nothing until a
49
65
 
50
66
  Per issue: **skip** / **skip + add override** / **fix** / **instructions**. For an override, offer only the applicable mechanism(s) and **name which one you'll write, showing the exact line/snippet first**:
51
67
 
52
- - **ESLint override** (mechanical findings) — `// eslint-disable-next-line <rule>` at the site, or a rule entry in the project's `eslint.config.*` override block.
68
+ - **Lint override** (mechanical findings) — `// oxlint-disable-next-line <rule>` (Vite+) or `// eslint-disable-next-line <rule>` at the site, or a rule entry in `lint.overrides` of `vite.config.ts` / the `eslint.config.*` override block.
53
69
  - **AI override → AGENTS.md** (rule-audit findings) — a general rule appended to `AGENTS.md # Custom Rules` (run `lint-prepare init` to create the file if missing). Prefer a general statement over a per-file exception unless it's genuinely a one-off.
54
- - **both** — when the violation is covered by an ESLint rule _and_ an agent rule.
70
+ - **both** — when the violation is covered by a lint rule _and_ an agent rule.
55
71
 
56
72
  ### 5. Report
57
73
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: lint-webstorm
3
- description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project files - excluded folders, Prettier & ESLint scopes, VCS, code style, Tailwind, JSON schemas, index exclusions. Use when setting up, checking or fixing a project's `.idea` configuration.
3
+ description: Templates and checks for JetBrains IDEA / WebStorm `.idea` project files - Oxc plugin (Vite+ - Oxlint, Oxfmt) or Prettier & ESLint scopes, excluded folders, VCS, code style, Tailwind, JSON schemas, index exclusions. Use when setting up, checking or fixing a project's `.idea` configuration.
4
4
  ---
5
5
 
6
6
  # Check
@@ -42,7 +42,59 @@ Compare the project's `.idea` files with the templates below and the `webstorm`
42
42
  </project>
43
43
  ```
44
44
 
45
- # Configure `.idea/prettier.xml`
45
+ # Vite+: Oxc plugin
46
+
47
+ When the project uses `vite-plus`: the [Oxc plugin](https://plugins.jetbrains.com/plugin/27061-oxc) runs `vp lint --lsp` / `vp fmt --lsp` (AUTOMATIC mode finds `vite-plus`), so the `vite.config.ts` blocks apply. Prettier is disabled and `.idea/jsLinters/eslint.xml` deleted. The plugin stores booleans as attributes while the Vite+ docs write `<option>` - keep both; the IDE rewrites the file in its own form on save. Ask the user to confirm Settings → Tools → Oxc after reopening.
48
+
49
+ `.idea/externalDependencies.xml` (required plugin; un-ignore it if `.idea` is gitignored: `!.idea/externalDependencies.xml`):
50
+
51
+ ```xml
52
+ <?xml version="1.0" encoding="UTF-8"?>
53
+ <project version="4">
54
+ <component name="ExternalDependencies">
55
+ <plugin id="com.github.oxc.project.oxcintellijplugin" />
56
+ </component>
57
+ </project>
58
+ ```
59
+
60
+ `.idea/OxcSettings.xml` (Oxlint, fix all on save):
61
+
62
+ ```xml
63
+ <?xml version="1.0" encoding="UTF-8"?>
64
+ <project version="4">
65
+ <component name="OxcSettings" configurationMode="AUTOMATIC" fixAllOnSave="true">
66
+ <option name="configurationMode" value="AUTOMATIC" />
67
+ <option name="fixAllOnSave" value="true" />
68
+ </component>
69
+ </project>
70
+ ```
71
+
72
+ `.idea/OxfmtSettings.xml` (Oxfmt, format on save, IDE code style from Oxfmt):
73
+
74
+ ```xml
75
+ <?xml version="1.0" encoding="UTF-8"?>
76
+ <project version="4">
77
+ <component name="OxfmtSettings" configurationMode="AUTOMATIC" fixAllOnSave="true" preferOxfmtCodeStyleSettings="true">
78
+ <option name="configurationMode" value="AUTOMATIC" />
79
+ <option name="fixAllOnSave" value="true" />
80
+ <option name="preferOxfmtCodeStyleSettings" value="true" />
81
+ </component>
82
+ </project>
83
+ ```
84
+
85
+ `.idea/prettier.xml`:
86
+
87
+ ```xml
88
+ <?xml version="1.0" encoding="UTF-8"?>
89
+ <project version="4">
90
+ <component name="PrettierConfiguration">
91
+ <option name="myConfigurationMode" value="DISABLED" />
92
+ <option name="myRunOnSave" value="false" />
93
+ </component>
94
+ </project>
95
+ ```
96
+
97
+ # Configure `.idea/prettier.xml` (without Vite+)
46
98
 
47
99
  ```xml
48
100
  <?xml version="1.0" encoding="UTF-8"?>
@@ -56,7 +108,7 @@ Compare the project's `.idea` files with the templates below and the `webstorm`
56
108
  </project>
57
109
  ```
58
110
 
59
- # Configure `.idea/jsLinters/eslint.xml`
111
+ # Configure `.idea/jsLinters/eslint.xml` (without Vite+)
60
112
 
61
113
  ```xml
62
114
  <?xml version="1.0" encoding="UTF-8"?>
@@ -112,6 +164,8 @@ AugmentWebviewStateStore.xml
112
164
 
113
165
  # Configure `.idea/codeStyles/codeStyleConfig.xml`
114
166
 
167
+ `DiS` is the owner's personal IDE scheme; other developers may not have it. With Vite+ Oxfmt drives the IDE code style (`preferOxfmtCodeStyleSettings` in `OxfmtSettings.xml`) whatever this file selects, so the project never depends on it:
168
+
115
169
  ```xml
116
170
  <component name="ProjectCodeStyleConfiguration">
117
171
  <state>
@@ -30,21 +30,78 @@ Procedures for an OpenSpec corpus. Five things live elsewhere and are not repeat
30
30
 
31
31
  Where the repository's `AGENTS.md` names a spec gate in its Checks list, such as `spec-tools gates`, run that gate: it runs `steward check --base auto` with the repository's binds. Elsewhere run `steward check --base auto` yourself. It compares the working tree with the branch point and checks the corpus and the files citing it. Add `--file <path>` to scope it, `--json` for machines, `--strict` to fail on warnings, and `--fix` for the safe mechanical repairs. A kind marked _base only_ runs only when a base is set, and under a base the prompts cover only what the diff added or edited.
32
32
 
33
- | Kind | Severity | What to do |
34
- | --- | --- | --- |
35
- | `dangling-citation` | error | Fix the path or anchor, or remove the citation. A citation is an optional pointer; the one rule is that it resolves. |
36
- | `renamed-anchor` | error, base only | `--fix` rewrites every citation of an anchor the diff renamed. |
37
- | `duplicate-anchor` | error | Two headings in one spec render the same slug. Rename one. |
38
- | `duplicate-requirement` | error | One requirement name in two capabilities, or one body twice. Keep it in the capability that owns the behaviour and reference it from the other. |
39
- | `size` | error past 500 words or 8 obligations, info past 300 or 5 | Split the requirement into coherent areas, never into one requirement per sentence ([model](references/model.md#tests-and-scenarios)). |
40
- | `scenario-unproven` | error, base only | A scenario you added or edited in a REQUIRED requirement has no binding. Cite it where its test, type assertion, lint entry or check proves it ([binding](references/contract.md#binding)); a test you add must catch a regression of that case. If no evidence can, the requirement takes a Known gap naming the scenario, or becomes ⚠️ ADVISORY — the owner's call. |
41
- | `weakened` | warn, base only | A rule was removed, lowered (MUST → SHOULD), lost an absolute, gained an exception or became advisory. **Stop and ask the owner** — unless they asked for exactly this. In a hand-back, map each finding to the decision that authorised it (a review item, a ticket, the owner's word) and list only the unmatched ones for a decision; a verbatim move is already reported as a rename. |
42
- | `textual-test` | warn | The test asserts on source, spec or doc text. Prefer a behavioural test, or a deterministic tool for structure. |
43
- | `marker-hygiene` | warn | `--fix` normalises a misspelt marker. A retired `**⚠️ Unenforced:**`, or a Known gap without a tracker, exempts nothing: replace it with Advisory, a tracked Known gap, or nothing, as the [model](references/model.md#advisory-known-gap-or-neither) says, and ask the owner, because each is a reclassification. |
44
- | `new-requirement` | info, base only | Say, in your reply, which observable failure it prevents and what cheapest evidence catches it. If there is none, it is advisory or belongs elsewhere. |
45
- | `absolute-unproven` | info | Name the absolute's exceptions, or confirm it has none. Advisory requirements are not reported. |
46
- | `impl-detail`, `vague-obligation`, `restating-scenario`, `duplicate-scenario`, `unbound-test` | info | Prompts for judgement, not orders. Answer them in the spec or in your reply. Never write a test just to silence one. |
47
- | `non-ears`, `non-bdd` | info, base only | Added or edited text only: write the statement in EARS and the scenario in Given/When/Then ([model](references/model.md#tests-and-scenarios)). Never fails. |
33
+ <table>
34
+ <thead>
35
+ <tr><th>Kind</th><th>Severity</th><th>What to do</th></tr>
36
+ </thead>
37
+ <tbody>
38
+ <tr>
39
+ <td><code>dangling-citation</code></td>
40
+ <td>error</td>
41
+ <td>Fix the path or anchor, or remove the citation. A citation is an optional pointer; the one rule is that it resolves.</td>
42
+ </tr>
43
+ <tr>
44
+ <td><code>renamed-anchor</code></td>
45
+ <td>error, base only</td>
46
+ <td><code>--fix</code> rewrites every citation of an anchor the diff renamed.</td>
47
+ </tr>
48
+ <tr>
49
+ <td><code>duplicate-anchor</code></td>
50
+ <td>error</td>
51
+ <td>Two headings in one spec render the same slug. Rename one.</td>
52
+ </tr>
53
+ <tr>
54
+ <td><code>duplicate-requirement</code></td>
55
+ <td>error</td>
56
+ <td>One requirement name in two capabilities, or one body twice. Keep it in the capability that owns the behaviour and reference it from the other.</td>
57
+ </tr>
58
+ <tr>
59
+ <td><code>size</code></td>
60
+ <td>error past 500 words or 8 obligations, info past 300 or 5</td>
61
+ <td>Split the requirement into coherent areas, never into one requirement per sentence (<a href="references/model.md#tests-and-scenarios">model</a>).</td>
62
+ </tr>
63
+ <tr>
64
+ <td><code>scenario-unproven</code></td>
65
+ <td>error, base only</td>
66
+ <td>A scenario you added or edited in a REQUIRED requirement has no binding. Cite it where its test, type assertion, lint entry or check proves it (<a href="references/contract.md#binding">binding</a>); a test you add must catch a regression of that case. If no evidence can, the requirement takes a Known gap naming the scenario, or becomes ⚠️ ADVISORY — the owner's call.</td>
67
+ </tr>
68
+ <tr>
69
+ <td><code>weakened</code></td>
70
+ <td>warn, base only</td>
71
+ <td>A rule was removed, lowered (MUST → SHOULD), lost an absolute, gained an exception or became advisory. <strong>Stop and ask the owner</strong> — unless they asked for exactly this. In a hand-back, map each finding to the decision that authorised it (a review item, a ticket, the owner's word) and list only the unmatched ones for a decision; a verbatim move is already reported as a rename.</td>
72
+ </tr>
73
+ <tr>
74
+ <td><code>textual-test</code></td>
75
+ <td>warn</td>
76
+ <td>The test asserts on source, spec or doc text. Prefer a behavioural test, or a deterministic tool for structure.</td>
77
+ </tr>
78
+ <tr>
79
+ <td><code>marker-hygiene</code></td>
80
+ <td>warn</td>
81
+ <td><code>--fix</code> normalises a misspelt marker. A retired <code>**⚠️ Unenforced:**</code>, or a Known gap without a tracker, exempts nothing: replace it with Advisory, a tracked Known gap, or nothing, as the <a href="references/model.md#advisory-known-gap-or-neither">model</a> says, and ask the owner, because each is a reclassification.</td>
82
+ </tr>
83
+ <tr>
84
+ <td><code>new-requirement</code></td>
85
+ <td>info, base only</td>
86
+ <td>Say, in your reply, which observable failure it prevents and what cheapest evidence catches it. If there is none, it is advisory or belongs elsewhere.</td>
87
+ </tr>
88
+ <tr>
89
+ <td><code>absolute-unproven</code></td>
90
+ <td>info</td>
91
+ <td>Name the absolute's exceptions, or confirm it has none. Advisory requirements are not reported.</td>
92
+ </tr>
93
+ <tr>
94
+ <td><code>impl-detail</code>, <code>vague-obligation</code>, <code>restating-scenario</code>, <code>duplicate-scenario</code>, <code>unbound-test</code></td>
95
+ <td>info</td>
96
+ <td>Prompts for judgement, not orders. Answer them in the spec or in your reply. Never write a test just to silence one.</td>
97
+ </tr>
98
+ <tr>
99
+ <td><code>non-ears</code>, <code>non-bdd</code></td>
100
+ <td>info, base only</td>
101
+ <td>Added or edited text only: write the statement in EARS and the scenario in Given/When/Then (<a href="references/model.md#tests-and-scenarios">model</a>). Never fails.</td>
102
+ </tr>
103
+ </tbody>
104
+ </table>
48
105
 
49
106
  The exact rule behind each kind is in [contract.md](references/contract.md#kinds-and-severities). The edit hook runs the per-file checks on each file you touch, with no ratchet, and feeds them back at once. Treat its message as you would this table.
50
107
 
@@ -35,7 +35,7 @@ A citation of a scenario's anchor binds the scenario only where it sits in one o
35
35
  | In a test file (a JavaScript or TypeScript `*.test.*`, `*.spec.*` or `*.test-d.*` file, a file under `__tests__/` or `e2e/`, or a Python or Go test file), inside a `describe`, `it`, `test`, `suite` or `bench` call, with any `.only`, `.skip`, `.concurrent`, `.sequential`, `.todo`, `.each(…)`, `.for(…)`, `.runIf(…)`, `.skipIf(…)` or `.fails` chain, and Playwright's `test.describe`, `test.step`, `.serial`, `.parallel`, `.fixme` and `.fail`; in a Python test file, inside a `test_…` function or a `Test…` class; in a Go test file, inside a `Test…` function | yes |
36
36
  | In a test file, in the comment run directly above such a call or function (in Python, its decorators too), with no blank line between | yes |
37
37
  | In a test file, on a type assertion — an `Expect<…>` type alias, or an `expectTypeOf(…)` or `assertType(…)` call — at the top level or inside a block | yes |
38
- | In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}` or `yarn.config.cjs` — anywhere | yes |
38
+ | In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}`, `vite.config.{js,mjs,cjs,ts,mts,cts}` (Vite+) or `yarn.config.cjs` — anywhere | yes |
39
39
  | In a file matching a `binds` glob the repository declares — `"spec-steward": { "binds": [...] }` in its root `package.json`, or `--binds <glob>` — (a check script, a Dockerfile, a CI configuration), anywhere | yes |
40
40
  | Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
41
41
  | Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
@@ -145,11 +145,11 @@ An explicit `--base <ref>` compares with the merge base of `<ref>` and `HEAD`. W
145
145
 
146
146
  ### Exit codes
147
147
 
148
- | Code | When |
149
- | --- | --- |
150
- | 0 | No error finding |
151
- | 1 | An error finding, or a warning under `--strict` |
152
- | 2 | A usage or environment error: an unknown flag, a base ref that does not exist, a git file listing that failed or came back empty, a missing specs directory |
148
+ | Code | When |
149
+ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
150
+ | 0 | No error finding |
151
+ | 1 | An error finding, or a warning under `--strict` |
152
+ | 2 | A usage or environment error: an unknown flag, a base ref that does not exist, a git file listing that failed or came back empty, a missing specs directory |
153
153
 
154
154
  Exit 2 on an empty listing keeps a broken checkout from passing a scan that read nothing.
155
155