@kirill.konshin/lint 0.7.1 → 0.7.2

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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kirill.konshin/lint",
3
3
  "description": "Vite+ (Oxlint + Oxfmt), ESLint + Prettier + lint-staged configs and AI agent rules/skills for monorepos",
4
- "version": "0.7.1",
4
+ "version": "0.7.2",
5
5
  "type": "module",
6
6
  "skipGenerate": true,
7
7
  "bin": {
package/rules/github.md CHANGED
@@ -7,7 +7,9 @@ paths:
7
7
  - '**/.github/**/*.yaml'
8
8
  ---
9
9
 
10
- - Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node with Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
10
+ - Agentic review MUST verify this effective CI order: checkout -> enable Corepack -> setup Node -> restore Yarn cache -> restore build caches -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
11
+ - Yarn cache: follow npm-yarn.md "Install on CI". Use the key `${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}` and the restore key `${{ runner.os }}-yarn-`.
12
+ - With an `install` job, only this job saves the Yarn cache. The other jobs `need` it and restore with `actions/cache/restore`. See the `lint-github` skill.
11
13
  - Key build caches per commit when jobs run one after another: key `${{ runner.os }}-<tool>-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-`. A later job gets an exact hit and does not save again.
12
14
  - Key build caches per job and commit when jobs run in parallel: key `${{ runner.os }}-<tool>-${{ github.job }}-${{ github.sha }}`, restore key `${{ runner.os }}-<tool>-${{ github.job }}-`. Only the first job that saves a key keeps its outputs. A downstream job restores the producing job's key and does not save.
13
15
  - With Nx Cloud (`nxCloudId` in `nx.json`): no `.nx` cache steps; workflow-level `env: NX_CLOUD_ACCESS_TOKEN` — `${{ secrets.NX_CLOUD_ACCESS_TOKEN }}` (read-write) in workflows that run only on `main`, `${{ secrets.NX_CLOUD_ACCESS_TOKEN_READ_ONLY }}` in PR workflows, both repository secrets (fork PRs get no secrets and run without the cache); see `lint-github` skill.
package/rules/gitlab.md CHANGED
@@ -10,6 +10,11 @@ paths:
10
10
  - Always collect coverage from tests
11
11
  - Always publish important build stats as artifacts
12
12
  - Agentic review MUST verify this effective CI order: checkout and cache restore -> enable Corepack -> immutable install -> prepare -> verification (lint/test/build) -> publish; publishing MUST depend on successful verification.
13
+ - Yarn cache: follow npm-yarn.md "Install on CI". Key it per branch, with the default branch as the fallback key.
14
+ - The fallback to the default-branch cache works only when "Use separate caches for protected branches" is cleared (Settings > CI/CD > General pipelines). Otherwise GitLab adds `-protected` or `-non_protected` to all keys, and other branches never find the default-branch cache. GitLab: clear it only when all users with the Developer role are highly trusted.
15
+ - With an `install` job, only this job has Yarn cache `policy: pull-push`. The other jobs use `policy: pull`. See the `lint-gitlab` skill.
16
+ - Use the fastzip archiver for cache and artifacts. It is the default from GitLab Runner 19.4. On older runners, set `FF_USE_FASTZIP: 'true'`.
17
+ - Set `CACHE_COMPRESSION_LEVEL: fastest` to pack and unpack the cache faster. This setting works only with fastzip.
13
18
  - Keep local build-cache keys job-specific in parallel pipelines; a remote Nx or Turbo cache is needed only to share results between different jobs.
14
19
  - With Nx Cloud (`nxCloudId` in `nx.json`): no `.nx` cache; `NX_CLOUD_ACCESS_TOKEN` is a masked **protected** CI/CD variable holding a read-write token (protected branches only), and merge-request pipelines map `NX_CLOUD_ACCESS_TOKEN: $NX_CLOUD_ACCESS_TOKEN_READ_ONLY` from a masked unprotected variable; see `lint-gitlab` skill.
15
20
  - Without Nx Cloud, when caching Nx locally, cache its DB as `.nx/workspace-data/default-v*.db` next to `.nx/cache`: rename it to the runner's machine ID in `before_script` (before install) and back to `default-v*.db` in `after_script`, otherwise Nx ignores the restored `.nx/cache` (see `lint-gitlab` skill).
package/rules/npm-yarn.md CHANGED
@@ -12,6 +12,7 @@ description: NPM & Yarn patterns
12
12
  - Workspace-wide root scripts use `vp run`, not `yarn workspaces foreach`: `"build": "vp run -r build"` (dependency order), `"start": "vp run -r --parallel start"`, `"clean": "vp run -r clean && rm -rf node_modules"`; `-r` includes the root package, so the root script's other steps run too
13
13
  - IF `vite-plus` is not installed, use the old style: package scripts with ESLint, Prettier, lint-staged, Husky
14
14
  - Vite+ requires the `node-modules` linker (no Yarn PnP) and pins `vite` to its core and `vitest` to its bundled version at the root (see the `@kirill.konshin/lint` README)
15
+ - NEVER use Yarn PnP (`nodeLinker: pnp`): Vite+ and most tools need `node_modules`. Move a project on PnP to `nodeLinker: node-modules`.
15
16
 
16
17
  # Lifecycle Scripts: `prepare` vs `postinstall`
17
18
 
@@ -100,8 +101,6 @@ Make sure `yarnPath` is not specified, rely on `packageManager` in `package.json
100
101
  approvedGitRepositories:
101
102
  - '**'
102
103
 
103
- compressionLevel: mixed
104
-
105
104
  # print install-time script output (postinstall / prepare, dependency builds) live instead of buffering it into a log
106
105
  enableInlineBuilds: true
107
106
 
@@ -116,6 +115,27 @@ npmPreapprovedPackages:
116
115
  - '@kirill.konshin/*'
117
116
  ```
118
117
 
118
+ # Install on CI
119
+
120
+ The single source for CI install rules. Platform steps: github.md, gitlab.md.
121
+
122
+ - On CI, set `YARN_ENABLE_GLOBAL_CACHE=false`. Yarn then keeps all packages in `.yarn/cache`, and CI caches this folder.
123
+ - Cache only `.yarn/cache`. NEVER cache `node_modules`: it has too many files to pack and unpack quickly.
124
+ - IF parallel jobs follow the install, add an `install` job. This job fills the Yarn cache and saves it. The other jobs only read it.
125
+ - IF the pipeline has one job, or its jobs run one after another, do not add an `install` job.
126
+ - Exception: a shared cache volume. IF all runners mount the same volume (for example a Kubernetes PVC):
127
+ - Set `YARN_ENABLE_GLOBAL_CACHE=true` and put the Yarn global folder on the volume (`YARN_GLOBAL_FOLDER`). Do not use the CI cache for packages.
128
+ - Hardlinks do not cross filesystems. Yarn hardlinks package files from `<globalFolder>/index`. The `node-modules` linker then copies instead and downgrades `nmMode: hardlinks-global` to `hardlinks-local`. The `pnpm` linker has no fallback: it fails with "cross-device link".
129
+ - With Yarn's `nodeLinker: pnpm`, put `pnpmStoreFolder` on the same volume as the global folder, one folder per branch (`/cache/yarn/store/$CI_COMMIT_REF_SLUG`). The link step then takes seconds.
130
+ - Each Yarn `pnpm` install deletes all store entries that it does not use. The per-branch folder keeps installs on other branches away from your store.
131
+ - With pnpm, set `store-dir` on the volume.
132
+ - Clean the volume with a scheduled job: the global cache only grows, and the stores of deleted branches stay.
133
+ - IF `yarn install` is still the CI bottleneck, measure it and evaluate alternatives. The principles of [Speed up NPM/Yarn install in Gitlab](https://www.konshin.org/publications/speed-up-npm-yarn-install-in-gitlab) ([Medium](https://medium.com/disdj/speed-up-npm-yarn-install-in-gitlab-1434437f9857)) still apply. Its tools are outdated.
134
+ - A faster linker: Yarn's `nodeLinker: pnpm` often links faster than `node-modules`, and pnpm is faster still. Both layouts are strict and not hoisted (see Hoisting). Undeclared dependencies fail, and Electron needs a hoisted layout. `@kirill.konshin/lint` is not verified with them.
135
+ - Jobs that need only some workspaces: `yarn workspaces focus <workspace>`
136
+ - A CI image with the dependencies installed
137
+ - IF in doubt, keep `nodeLinker: node-modules`.
138
+
119
139
  # Yalc (Local Package Linking)
120
140
 
121
141
  Test unpublished packages in sibling projects (yalc is a root devDependency here):
package/rules/vite.md CHANGED
@@ -6,9 +6,14 @@ paths:
6
6
  - '**/vitest.config.ts'
7
7
  ---
8
8
 
9
+ # Vite+ (vite-plus, vp)
10
+
9
11
  - 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
12
  - Libraries build with `vp pack` (`pack` block, tsdown), apps with `vp build`, tests run with `vp test` and import from `vite-plus/test`
11
13
  - Keep `lint`/`fmt` in the root config only; per-package settings go to `lint.overrides`/`fmt.overrides`
14
+
15
+ # Vitest
16
+
12
17
  - Web Worker Polyfill `import '@vitest/web-worker';`
13
18
  - In monorepo define root vitest project https://vitest.dev/guide/projects.html#defining-projects
14
19
 
@@ -3,7 +3,13 @@ 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.
6
+ Reference CI: two local composite actions and a workflow. Install and cache rules: npm-yarn.md "Install on CI" and github.md.
7
+
8
+ - The `install` job fills the Yarn cache (`setup` with `yarn-cache: warm`).
9
+ - The checks run after it as parallel jobs. They only restore the cache (`yarn-cache: restore`).
10
+ - The publish job needs all checks.
11
+ - A workflow with one job, or with jobs that run one after another, has no `install` job. It uses the default `yarn-cache: save`.
12
+ - Self-hosted runners with a shared cache volume: remove the `Use local Yarn cache` step and the Yarn cache steps from `setup` (npm-yarn.md "Install on CI").
7
13
 
8
14
  # With Nx Cloud (`nxCloudId` in `nx.json`)
9
15
 
@@ -121,10 +127,24 @@ inputs:
121
127
  description: Job whose Nx cache to restore (defaults to this job); a job that does not save reuses another job's cache
122
128
  required: false
123
129
  default: ''
130
+ yarn-cache:
131
+ description: 'save: restore, install, save on a miss. warm: the install job, fills and saves the cache, does not install. restore: a job after the install job, restores only.'
132
+ required: false
133
+ default: save
124
134
 
125
135
  runs:
126
136
  using: composite
127
137
  steps:
138
+ - name: Check yarn-cache
139
+ if: inputs.yarn-cache != 'save' && inputs.yarn-cache != 'warm' && inputs.yarn-cache != 'restore'
140
+ shell: bash
141
+ run: echo "::error::yarn-cache must be save, warm or restore, got '${{ inputs.yarn-cache }}'" && exit 1
142
+
143
+ # All packages go to .yarn/cache, the folder that CI caches (npm-yarn.md "Install on CI")
144
+ - name: Use local Yarn cache
145
+ run: echo "YARN_ENABLE_GLOBAL_CACHE=false" >> "$GITHUB_ENV"
146
+ shell: bash
147
+
128
148
  - name: Enable Corepack
129
149
  run: corepack enable
130
150
  shell: bash
@@ -134,14 +154,39 @@ runs:
134
154
  with:
135
155
  node-version: 24
136
156
  registry-url: ${{ inputs.registry-url }}
137
- cache: yarn
138
- cache-dependency-path: yarn.lock
157
+
158
+ - name: Look up Yarn cache
159
+ id: lookup
160
+ if: inputs.yarn-cache == 'warm'
161
+ uses: actions/cache/restore@v6
162
+ with:
163
+ path: .yarn/cache
164
+ key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
165
+ lookup-only: true
166
+
167
+ # An older cache is safe: install fetches only the missing packages
168
+ - name: Restore Yarn cache
169
+ id: restore
170
+ if: steps.lookup.outputs.cache-hit != 'true'
171
+ uses: actions/cache/restore@v6
172
+ with:
173
+ path: .yarn/cache
174
+ key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
175
+ restore-keys: |
176
+ ${{ runner.os }}-yarn-
177
+
178
+ # The install job only fills the Yarn cache: no build caches, no install, no prepare
179
+ - name: Fetch dependencies
180
+ if: inputs.yarn-cache == 'warm' && steps.lookup.outputs.cache-hit != 'true'
181
+ run: yarn install --immutable --mode=skip-build
182
+ shell: bash
139
183
 
140
184
  # If project uses Turbo
141
185
  #TODO https://turbo.build/repo/docs/guides/ci-vendors/github-actions#remote-caching
142
186
  #TODO https://turborepo.dev/docs/guides/ci-vendors/github-actions#remote-caching-with-github-actionscache
143
187
  # 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
188
  - name: Cache Turbo
189
+ if: inputs.yarn-cache != 'warm'
145
190
  uses: actions/cache@v6
146
191
  with:
147
192
  path: .turbo
@@ -152,16 +197,27 @@ runs:
152
197
 
153
198
  # If project uses Nx
154
199
  - name: Restore Nx cache
200
+ if: inputs.yarn-cache != 'warm'
155
201
  uses: ./.github/actions/nx-cache
156
202
  with:
157
203
  job: ${{ inputs.nx-cache }}
158
204
 
159
205
  - name: Install dependencies
206
+ if: inputs.yarn-cache != 'warm'
160
207
  run: yarn install --immutable
161
208
  shell: bash
162
209
 
210
+ # Directly after install: a failed check later does not stop the save
211
+ - name: Save Yarn cache
212
+ if: inputs.yarn-cache != 'restore' && steps.lookup.outputs.cache-hit != 'true' && steps.restore.outputs.cache-hit != 'true'
213
+ uses: actions/cache/save@v6
214
+ with:
215
+ path: .yarn/cache
216
+ key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
217
+
163
218
  # Add this if Yarn 2+ is used and package is NOT private, otherwise postinstall should be configured, and this block skipped
164
219
  - name: Prepare
220
+ if: inputs.yarn-cache != 'warm'
165
221
  run: yarn prepare
166
222
  shell: bash
167
223
  ```
@@ -183,10 +239,23 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}
183
239
 
184
240
  env:
185
241
  TURBO_CACHE_DIR: .turbo # if project uses Turbo
186
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
187
242
 
188
- # Checks run as parallel jobs; release needs all of them. Only jobs with their own Nx cache save it.
243
+ # The checks run as parallel jobs after install. They only restore the Yarn cache. Release needs all checks.
244
+ # Only jobs with their own Nx cache save it.
189
245
  jobs:
246
+ install:
247
+ name: Install
248
+ runs-on: ubuntu-latest
249
+
250
+ steps:
251
+ - name: Checkout Repo
252
+ uses: actions/checkout@v7
253
+
254
+ - name: Setup
255
+ uses: ./.github/actions/setup
256
+ with:
257
+ yarn-cache: warm
258
+
190
259
  lint:
191
260
  name: Lint
192
261
  runs-on: ubuntu-latest
@@ -201,6 +270,7 @@ jobs:
201
270
  uses: ./.github/actions/setup
202
271
  with:
203
272
  nx-cache: build # reuses the build job's cache; this job does not save
273
+ yarn-cache: restore
204
274
 
205
275
  # type checks read the built declarations of workspace packages
206
276
  - name: Build packages
@@ -212,6 +282,7 @@ jobs:
212
282
  test:
213
283
  name: Test
214
284
  runs-on: ubuntu-latest
285
+ needs: install
215
286
 
216
287
  steps:
217
288
  - name: Checkout Repo
@@ -219,6 +290,8 @@ jobs:
219
290
 
220
291
  - name: Setup
221
292
  uses: ./.github/actions/setup
293
+ with:
294
+ yarn-cache: restore
222
295
 
223
296
  - name: Test
224
297
  run: yarn test
@@ -231,6 +304,7 @@ jobs:
231
304
  build:
232
305
  name: Build
233
306
  runs-on: ubuntu-latest
307
+ needs: install
234
308
 
235
309
  steps:
236
310
  - name: Checkout Repo
@@ -238,6 +312,8 @@ jobs:
238
312
 
239
313
  - name: Setup
240
314
  uses: ./.github/actions/setup
315
+ with:
316
+ yarn-cache: restore
241
317
 
242
318
  - name: Build
243
319
  run: yarn build
@@ -270,6 +346,7 @@ jobs:
270
346
  with:
271
347
  registry-url: 'https://registry.npmjs.org' # publish job needs .npmrc auth config
272
348
  nx-cache: build # exact key of the build job's cache; this job does not save
349
+ yarn-cache: restore
273
350
 
274
351
  # Different runner: outputs come from the build job's Nx cache, so nothing should rebuild
275
352
  - name: Build
@@ -26,17 +26,25 @@ workflow:
26
26
  ```yml
27
27
  image: node:lts
28
28
 
29
+ # Install and cache rules: npm-yarn.md "Install on CI" and gitlab.md
29
30
  variables:
30
- YARN_ENABLE_GLOBAL_CACHE: false # so that .yarn/cache is written
31
+ YARN_ENABLE_GLOBAL_CACHE: false # all packages go to .yarn/cache, the folder that CI caches
32
+ FF_USE_FASTZIP: 'true' # only for GitLab Runner < 19.4, where fastzip is not the default
33
+ CACHE_COMPRESSION_LEVEL: fastest # packs and unpacks the cache faster; needs fastzip
34
+
35
+ # An older cache is safe: install fetches only the missing packages
36
+ .yarn-cache: &yarn-cache
37
+ key: yarn-$CI_COMMIT_REF_SLUG
38
+ fallback_keys:
39
+ # Found only when "Use separate caches for protected branches" is cleared (gitlab.md)
40
+ - yarn-$CI_DEFAULT_BRANCH
41
+ paths:
42
+ - .yarn/cache
31
43
 
32
44
  cache:
33
- - key:
34
- prefix: yarn
35
- files:
36
- - yarn.lock # dependencies cached based on lockfile
37
- paths:
38
- - .yarn/cache
39
- policy: pull-push
45
+ # Pull only: the install job uploads it. Without an install job, use pull-push.
46
+ - <<: *yarn-cache
47
+ policy: pull
40
48
  # Job-specific keys prevent parallel jobs from replacing each other's local build cache.
41
49
  - key: build-$CI_JOB_NAME_SLUG-$CI_COMMIT_REF_SLUG
42
50
  fallback_keys:
@@ -84,8 +92,13 @@ after_script:
84
92
  [ -z "$db" ] || [ "$db" = "$to" ] || mv -f "$db" "$to"
85
93
  echo "Nx cache DB to save: $(ls $d/default-v*.db 2>/dev/null || echo none)"
86
94
 
95
+ # Fills the Yarn cache before the parallel jobs start. It is the only job that uploads the Yarn cache.
96
+ # before_script does the install.
87
97
  install:
88
98
  stage: install
99
+ cache:
100
+ - <<: *yarn-cache
101
+ policy: pull-push
89
102
  script:
90
103
  - echo Done
91
104
 
@@ -119,3 +132,43 @@ build:
119
132
  paths:
120
133
  - web/build
121
134
  ```
135
+
136
+ # Shared Cache Volume
137
+
138
+ Use this when all runners mount the same volume (npm-yarn.md "Install on CI"). The packages stay on the volume. No job uploads or downloads them.
139
+
140
+ Runner config (Kubernetes executor, a ReadWriteMany PVC):
141
+
142
+ ```toml
143
+ [[runners.kubernetes.volumes.pvc]]
144
+ name = "cache-yarn"
145
+ mount_path = "/cache/yarn"
146
+ ```
147
+
148
+ Pipeline changes:
149
+
150
+ - Remove the `.yarn-cache` entries.
151
+ - Set these variables. Keep the global folder and the store on this one volume: the `pnpm` linker cannot hardlink across filesystems.
152
+ - With `nodeLinker: node-modules`, remove the `install` job. With `nodeLinker: pnpm`, keep it without its `cache:` entry: it fills the branch store before the parallel jobs start.
153
+
154
+ ```yml
155
+ variables:
156
+ YARN_ENABLE_GLOBAL_CACHE: 'true' # explicit: a .yarnrc.yml can turn it off
157
+ YARN_GLOBAL_FOLDER: /cache/yarn # global cache in /cache/yarn/cache, hardlink index in /cache/yarn/index
158
+ YARN_PNPM_STORE_FOLDER: /cache/yarn/store/$CI_COMMIT_REF_SLUG # only with nodeLinker: pnpm; one store per branch
159
+ ```
160
+
161
+ Clean the volume on a schedule (Build > Pipeline schedules, variable `CLEAR_CACHE: 'true'`). Run it at a quiet time: a job that installs during the cleanup can fail.
162
+
163
+ ```yml
164
+ clear-cache:
165
+ stage: .post
166
+ rules:
167
+ - if: $CI_PIPELINE_SOURCE == "schedule" && $CLEAR_CACHE == "true"
168
+ cache: []
169
+ before_script: [] # no install
170
+ after_script: []
171
+ script:
172
+ - rm -rf /cache/yarn/store/* # stores of deleted branches; active branches refill from the index
173
+ - rm -rf /cache/yarn/cache/* /cache/yarn/index/* # the global cache and the index only grow
174
+ ```
@@ -13,7 +13,7 @@ Only what changes between versions; the target setup is the package README (`nod
13
13
 
14
14
  # 0.6 -> 0.7
15
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.
16
+ 0.7 recommends Vite+. Keep the ESLint / Prettier / lint-staged exports only if the user declines Vite+. Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
17
17
 
18
18
  - **Prerequisites**: Node `^22.18 || ^24.11 || >=26`, Vite 8+, Vitest 4.1+, `node-modules` linker
19
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`
@@ -16,7 +16,9 @@ Full config templates: `node_modules/@kirill.konshin/lint/README.md`
16
16
 
17
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
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).
19
+ Vite+ is the default. Use the ESLint + Prettier flow only when the user declines Vite+.
20
+
21
+ Do not use Yarn PnP (npm-yarn.md). IF the project uses PnP, ask the user to move it to `nodeLinker: node-modules` first.
20
22
 
21
23
  ### Vite+
22
24