@kirill.konshin/lint 0.6.7 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +253 -94
  2. package/dist/configs/imports.js +3 -30
  3. package/dist/configs/react.d.ts +0 -15
  4. package/dist/configs/react.js +2 -36
  5. package/dist/configs/tailwind.d.ts +10 -0
  6. package/dist/configs/tailwind.js +25 -9
  7. package/dist/configs/testing.js +2 -41
  8. package/dist/configs/unicorn.js +2 -10
  9. package/dist/conventions.d.ts +12 -0
  10. package/dist/conventions.js +53 -0
  11. package/dist/index.d.ts +4 -4
  12. package/dist/index.js +4 -4
  13. package/dist/lib.d.ts +18 -1
  14. package/dist/lib.js +36 -2
  15. package/dist/lintPrepare.d.ts +2 -1
  16. package/dist/lintPrepare.js +13 -1
  17. package/dist/oxlintPlugin.d.ts +10 -0
  18. package/dist/oxlintPlugin.js +13 -0
  19. package/dist/testColocation.d.ts +10 -0
  20. package/dist/testColocation.js +45 -0
  21. package/dist/vitePlus.d.ts +58 -0
  22. package/dist/vitePlus.js +434 -0
  23. package/package.json +32 -9
  24. package/rules/agent.md +3 -0
  25. package/rules/code-style.md +1 -1
  26. package/rules/github.md +4 -1
  27. package/rules/gitlab.md +3 -5
  28. package/rules/jest.md +1 -1
  29. package/rules/markdown.md +11 -0
  30. package/rules/monorepo-turbo-nx.md +9 -0
  31. package/rules/mui.md +0 -2
  32. package/rules/npm-yarn.md +10 -1
  33. package/rules/nx.md +3 -1
  34. package/rules/playwright.md +18 -0
  35. package/rules/react.md +1 -3
  36. package/rules/tailwind.md +1 -0
  37. package/rules/testing.md +5 -2
  38. package/rules/typescript.md +5 -4
  39. package/rules/vite.md +5 -1
  40. package/{rules/electron.md → skills/lint-electron/SKILL.md} +5 -3
  41. package/skills/lint-github/SKILL.md +244 -42
  42. package/skills/lint-gitlab/SKILL.md +46 -1
  43. package/skills/lint-migrate/SKILL.md +24 -0
  44. package/skills/lint-repo/SKILL.md +21 -5
  45. package/skills/lint-webstorm/SKILL.md +55 -3
  46. package/skills/spec-steward/SKILL.md +72 -15
  47. package/skills/spec-steward/references/contract.md +6 -6
  48. package/skills/spec-tools/SKILL.md +11 -11
  49. package/skills/spec-tools/references/rules/common.md +32 -7
  50. package/skills/spec-tools/scripts/cli.js +18 -12
@@ -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()],
@@ -1,16 +1,18 @@
1
1
  ---
2
- type: always_apply
3
- description: Set of rules for projects which use Electron
2
+ name: lint-electron
3
+ description: Skill for Electron-based apps
4
4
  ---
5
5
 
6
6
  # CI Builds
7
7
 
8
+ ## Gitlab
9
+
8
10
  ```yml
9
11
  variables:
10
12
  USE_HARD_LINKS: 'false' # https://github.com/electron-userland/electron-builder/issues/3179#issuecomment-408347702
11
13
 
12
14
  build:
13
- image: macos-12-xcode-13
15
+ image: macos-12-xcode-13 # not exact version, but the point is to use macos-compatible image
14
16
  tags:
15
17
  - shared-macos-amd64
16
18
  script:
@@ -3,6 +3,171 @@ name: lint-github
3
3
  description: Describes how to work with Github & example workflow as a reference which essential jobs and concepts usual Github Workflow should have
4
4
  ---
5
5
 
6
+ Reference CI: two local composite actions and a workflow. Checks run as parallel jobs; publishing needs all of them.
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
+
32
+ `.github/actions/nx-cache/action.yml` — Nx 20+ ignores a restored `.nx/cache` without its DB:
33
+
34
+ ```yml
35
+ name: Nx cache
36
+ description: Caches .nx/cache with the Nx DB under the fixed name default-v*.db. Restore runs before install (./.github/actions/setup does it); save is the last step of a job that keeps its Nx outputs.
37
+
38
+ inputs:
39
+ mode:
40
+ description: restore | save
41
+ required: false
42
+ default: restore
43
+ job:
44
+ description: Job whose cache to use (defaults to this job); save only your own job's cache, parallel jobs must not share a key
45
+ required: false
46
+ default: ''
47
+
48
+ runs:
49
+ using: composite
50
+ steps:
51
+ - name: Check mode
52
+ if: inputs.mode != 'restore' && inputs.mode != 'save'
53
+ shell: bash
54
+ run: echo "::error::nx-cache mode must be restore or save, got '${{ inputs.mode }}'" && exit 1
55
+
56
+ # Nx indexes .nx/cache in a SQLite DB, cached next to it as default-v*.db.
57
+ # One key per job and commit: parallel jobs never race for a key.
58
+ - name: Restore Nx cache
59
+ if: inputs.mode == 'restore'
60
+ uses: actions/cache/restore@v6
61
+ with:
62
+ path: |
63
+ .nx/cache
64
+ .nx/workspace-data/default-v*.db
65
+ key: ${{ runner.os }}-nx-${{ inputs.job || github.job }}-${{ github.sha }}
66
+ restore-keys: |
67
+ ${{ runner.os }}-nx-${{ inputs.job || github.job }}-
68
+ ${{ runner.os }}-nx-
69
+
70
+ # Nx names the DB after the machine ID and ignores outputs it has no DB records for.
71
+ # Give the DB this runner's ID before install (postinstall runs Nx).
72
+ - name: Adopt Nx cache DB
73
+ if: inputs.mode == 'restore'
74
+ shell: bash
75
+ run: |
76
+ d=.nx/workspace-data
77
+ id=$(cat /var/lib/dbus/machine-id 2>/dev/null || cat /etc/machine-id 2>/dev/null || echo machine)
78
+ db=$(ls $d/default-v*.db 2>/dev/null | head -n 1 || true)
79
+ if [ -z "$db" ]; then
80
+ rm -rf .nx/cache # outputs without their DB are unusable
81
+ else
82
+ to=$d/$id-v${db##*-v}
83
+ rm -f "$to" "$to-wal" "$to-shm"
84
+ mv "$db" "$to"
85
+ fi
86
+ echo "Nx cache DB for machine ID $id: $(ls $d/*.db 2>/dev/null || echo none)"
87
+
88
+ # After the last Nx step: store the DB under the fixed name the cache holds
89
+ - name: Store Nx cache DB
90
+ if: inputs.mode == 'save'
91
+ shell: bash
92
+ run: |
93
+ d=.nx/workspace-data
94
+ db=$(ls -t $d/*-v*.db 2>/dev/null | head -n 1 || true)
95
+ to=$d/default-v${db##*-v}
96
+ [ -z "$db" ] || [ "$db" = "$to" ] || mv -f "$db" "$to"
97
+ echo "Nx cache DB to save: $(ls $d/default-v*.db 2>/dev/null || echo none)"
98
+
99
+ - name: Save Nx cache
100
+ if: inputs.mode == 'save'
101
+ uses: actions/cache/save@v6
102
+ with:
103
+ path: |
104
+ .nx/cache
105
+ .nx/workspace-data/default-v*.db
106
+ key: ${{ runner.os }}-nx-${{ inputs.job || github.job }}-${{ github.sha }}
107
+ ```
108
+
109
+ `.github/actions/setup/action.yml`:
110
+
111
+ ```yml
112
+ name: Setup
113
+ description: Node.js + Corepack + build cache restore + Yarn install. The repo must already be checked out (a local action cannot run before checkout). Jobs that keep their Nx outputs end with ./.github/actions/nx-cache (mode save).
114
+
115
+ inputs:
116
+ registry-url:
117
+ description: npm registry URL — set only on jobs that publish (configures .npmrc auth)
118
+ required: false
119
+ default: ''
120
+ nx-cache:
121
+ description: Job whose Nx cache to restore (defaults to this job); a job that does not save reuses another job's cache
122
+ required: false
123
+ default: ''
124
+
125
+ runs:
126
+ using: composite
127
+ steps:
128
+ - name: Enable Corepack
129
+ run: corepack enable
130
+ shell: bash
131
+
132
+ - name: Setup Node.js
133
+ uses: actions/setup-node@v6
134
+ with:
135
+ node-version: 24
136
+ registry-url: ${{ inputs.registry-url }}
137
+ cache: yarn
138
+ cache-dependency-path: yarn.lock
139
+
140
+ # If project uses Turbo
141
+ #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
142
+ #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
143
+ # One entry per commit when jobs run one after another; for parallel jobs add ${{ github.job }} to key and restore key (only the first job that saves a key keeps its outputs)
144
+ - name: Cache Turbo
145
+ uses: actions/cache@v6
146
+ with:
147
+ path: .turbo
148
+ key: ${{ runner.os }}-turbo-${{ github.job }}-${{ github.sha }}
149
+ restore-keys: |
150
+ ${{ runner.os }}-turbo-${{ github.job }}-
151
+ ${{ runner.os }}-turbo-
152
+
153
+ # If project uses Nx
154
+ - name: Restore Nx cache
155
+ uses: ./.github/actions/nx-cache
156
+ with:
157
+ job: ${{ inputs.nx-cache }}
158
+
159
+ - name: Install dependencies
160
+ run: yarn install --immutable
161
+ shell: bash
162
+
163
+ # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
164
+ - name: Prepare
165
+ run: yarn prepare
166
+ shell: bash
167
+ ```
168
+
169
+ `.github/workflows/release.yml`:
170
+
6
171
  ```yml
7
172
  name: Release
8
173
 
@@ -11,20 +176,82 @@ on:
11
176
  branches:
12
177
  - main
13
178
 
14
- # If project publishes to NPM
15
179
  permissions:
16
- id-token: write # Required for OIDC
17
180
  contents: read
18
181
 
19
182
  concurrency: ${{ github.workflow }}-${{ github.ref }}
20
183
 
184
+ env:
185
+ TURBO_CACHE_DIR: .turbo # if project uses Turbo
186
+ YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
187
+
188
+ # Checks run as parallel jobs; release needs all of them. Only jobs with their own Nx cache save it.
21
189
  jobs:
190
+ lint:
191
+ name: Lint
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
195
+
196
+ steps:
197
+ - name: Checkout Repo
198
+ uses: actions/checkout@v7
199
+
200
+ - name: Setup
201
+ uses: ./.github/actions/setup
202
+ with:
203
+ nx-cache: build # reuses the build job's cache; this job does not save
204
+
205
+ # type checks read the built declarations of workspace packages
206
+ - name: Build packages
207
+ run: yarn build # the orchestrator, cache hits
208
+
209
+ - name: Lint
210
+ run: yarn vp check # Vite+: format + lint + type checks, no --fix; without Vite+: yarn lint
211
+
212
+ test:
213
+ name: Test
214
+ runs-on: ubuntu-latest
215
+
216
+ steps:
217
+ - name: Checkout Repo
218
+ uses: actions/checkout@v7
219
+
220
+ - name: Setup
221
+ uses: ./.github/actions/setup
222
+
223
+ - name: Test
224
+ run: yarn test
225
+
226
+ - name: Save Nx cache
227
+ uses: ./.github/actions/nx-cache
228
+ with:
229
+ mode: save
230
+
231
+ build:
232
+ name: Build
233
+ runs-on: ubuntu-latest
234
+
235
+ steps:
236
+ - name: Checkout Repo
237
+ uses: actions/checkout@v7
238
+
239
+ - name: Setup
240
+ uses: ./.github/actions/setup
241
+
242
+ - name: Build
243
+ run: yarn build
244
+
245
+ - name: Save Nx cache
246
+ uses: ./.github/actions/nx-cache
247
+ with:
248
+ mode: save
249
+
22
250
  release:
23
251
  name: Release
24
252
  runs-on: ubuntu-latest
25
- env:
26
- TURBO_CACHE_DIR: .turbo # if project uses Turbo
27
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
253
+
254
+ needs: [lint, test, build]
28
255
 
29
256
  # If project publishes to NPM
30
257
  # https://davistobias.com/articles/adding-changeset/#2.1.b-adding-changeset-to-github-workflows
@@ -36,43 +263,18 @@ jobs:
36
263
 
37
264
  steps:
38
265
  - name: Checkout Repo
39
- uses: actions/checkout@v4
40
-
41
- - name: Enable Corepack
42
- run: corepack enable
266
+ uses: actions/checkout@v7
43
267
 
44
- - name: Setup Node.js
45
- uses: actions/setup-node@v6
268
+ - name: Setup
269
+ uses: ./.github/actions/setup
46
270
  with:
47
- node-version: 24
48
- registry-url: 'https://registry.npmjs.org'
49
- cache: yarn
50
- cache-dependency-path: yarn.lock
51
-
52
- #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
53
- #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
54
- - name: Cache Turbo
55
- uses: actions/cache@v6
56
- with:
57
- path: .turbo
58
- key: ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
59
- restore-keys: |
60
- ${{ runner.os }}-turbo-${{ github.run_id }}-${{ github.run_attempt }}-
61
- ${{ runner.os }}-turbo-
62
-
63
- - name: Cache Nx
64
- uses: actions/cache@v6
65
- with:
66
- path: .nx/cache
67
- key: ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
68
- restore-keys: |
69
- ${{ runner.os }}-nx-${{ github.run_id }}-${{ github.run_attempt }}-
70
- ${{ runner.os }}-nx-
71
-
72
- - name: Install dependencies
73
- run: yarn install --immutable
74
-
75
- # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
76
- - name: Prepare
77
- run: yarn prepare
271
+ registry-url: 'https://registry.npmjs.org' # publish job needs .npmrc auth config
272
+ nx-cache: build # exact key of the build job's cache; this job does not save
273
+
274
+ # Different runner: outputs come from the build job's Nx cache, so nothing should rebuild
275
+ - name: Build
276
+ run: yarn build
277
+
278
+ - name: Release
279
+ run: yarn release # the project's publish command
78
280
  ```
@@ -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
 
@@ -24,6 +44,7 @@ cache:
24
44
  paths:
25
45
  - .turbo
26
46
  - .nx/cache
47
+ - .nx/workspace-data/default-v*.db # Nx indexes .nx/cache in a SQLite DB, cached under this fixed name
27
48
  - '**/.tscache'
28
49
  - '**/.tsbuildinfo'
29
50
  - '**/.next/cache'
@@ -37,9 +58,32 @@ stages:
37
58
  # separate so that cache can pre-populate if other steps would fail, it speeds things up
38
59
  before_script:
39
60
  - corepack enable
61
+ # Nx names the DB after the machine ID and ignores outputs it has no DB records for.
62
+ # Give the DB this runner's ID before install (postinstall may run Nx).
63
+ - |
64
+ d=.nx/workspace-data
65
+ id=$(cat /var/lib/dbus/machine-id 2>/dev/null || cat /etc/machine-id 2>/dev/null || echo machine)
66
+ db=$(ls $d/default-v*.db 2>/dev/null | head -n 1 || true)
67
+ if [ -z "$db" ]; then
68
+ rm -rf .nx/cache # outputs without their DB are unusable
69
+ else
70
+ to=$d/$id-v${db##*-v}
71
+ rm -f "$to" "$to-wal" "$to-shm"
72
+ mv "$db" "$to"
73
+ fi
74
+ echo "Nx cache DB for machine ID $id: $(ls $d/*.db 2>/dev/null || echo none)"
40
75
  - yarn install --immutable
41
76
  - yarn prepare # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this line skipped
42
77
 
78
+ # GitLab saves the cache after after_script: store the DB under the fixed name the cache holds
79
+ after_script:
80
+ - |
81
+ d=.nx/workspace-data
82
+ db=$(ls -t $d/*-v*.db 2>/dev/null | head -n 1 || true)
83
+ to=$d/default-v${db##*-v}
84
+ [ -z "$db" ] || [ "$db" = "$to" ] || mv -f "$db" "$to"
85
+ echo "Nx cache DB to save: $(ls $d/default-v*.db 2>/dev/null || echo none)"
86
+
43
87
  install:
44
88
  stage: install
45
89
  script:
@@ -48,7 +92,8 @@ install:
48
92
  lint:
49
93
  stage: test
50
94
  script:
51
- - 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
52
97
 
53
98
  test:
54
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`.
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