@zairakai/js-dev-tools 3.19.0 → 3.21.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 (48) hide show
  1. package/.editorconfig +6 -72
  2. package/.gitlab/ci/parts/base.yml +95 -0
  3. package/.gitlab/ci/parts/publish.yml +156 -0
  4. package/.gitlab/ci/parts/quality.yml +161 -0
  5. package/.gitlab/ci/parts/security.yml +40 -0
  6. package/.gitlab/ci/parts/updates.yml +60 -0
  7. package/.gitlab/ci/pipeline-js-app.yml +19 -38
  8. package/.gitlab/ci/pipeline-js-package.yml +23 -528
  9. package/README.md +51 -6
  10. package/config/.markdownlintignore +9 -1
  11. package/config/.prettierignore +8 -0
  12. package/config/.stylelintignore +7 -0
  13. package/config/eslint.config.js +7 -1
  14. package/config/knip.config.js +2 -2
  15. package/package.json +33 -29
  16. package/scripts/build.sh +28 -28
  17. package/scripts/ci-quality.sh +6 -6
  18. package/scripts/config.sh +164 -148
  19. package/scripts/doctor.sh +12 -12
  20. package/scripts/eslint-fix.sh +8 -8
  21. package/scripts/eslint.sh +15 -15
  22. package/scripts/install-bats.sh +143 -146
  23. package/scripts/install-hooks.sh +108 -111
  24. package/scripts/install-markdownlint.sh +4 -4
  25. package/scripts/install-shellcheck.sh +135 -138
  26. package/scripts/knip.sh +7 -7
  27. package/scripts/markdownlint.sh +38 -38
  28. package/scripts/outdated.sh +30 -29
  29. package/scripts/prettier-fix.sh +13 -13
  30. package/scripts/prettier.sh +13 -13
  31. package/scripts/setup-project.sh +691 -629
  32. package/scripts/stylelint-fix.sh +17 -17
  33. package/scripts/stylelint.sh +18 -18
  34. package/scripts/test.sh +13 -11
  35. package/scripts/typecheck.sh +11 -11
  36. package/scripts/update-dependencies.mjs +68 -68
  37. package/scripts/validate-shellcheck.sh +18 -18
  38. package/stubs/githooks/commit-msg +18 -18
  39. package/stubs/githooks/pre-commit +19 -19
  40. package/stubs/githooks/pre-push +18 -18
  41. package/stubs/githooks/prepare-commit-msg +6 -6
  42. package/stubs/gitlab-ci/gitlab-ci.yml.stub +1 -1
  43. package/stubs/governance/CONTRIBUTING.md.stub +5 -3
  44. package/stubs/quality/eslint.config.js.stub +1 -1
  45. package/stubs/quality/knip.config.js.stub +1 -1
  46. package/stubs/style/prettier.config.js.stub +3 -3
  47. package/stubs/style/stylelint.config.js.stub +1 -1
  48. package/stubs/testing/vitest.config.js.stub +1 -1
@@ -1,55 +1,45 @@
1
- # ================================
2
- # PIPELINE TEMPLATE — NPM Package
3
- # ================================
1
+ # PIPELINE TEMPLATE - NPM Package
2
+ # ================
4
3
  # Shared pipeline template for NPM packages in the Zairakai namespace.
5
- # Self-contained: anchors and jobs are all in this single file.
6
- # YAML anchors do not survive cross-file include: — this is a YAML parser
7
- # limitation, not a GitLab one. Everything is therefore kept here.
4
+ # The jobs are in the files of parts/, one per role, which pipeline-js-app.yml includes too (the part that an application
5
+ # needs): base (runner, variables, hidden jobs), security, quality (install, validate, quality, test), updates, and
6
+ # publish (build, publish, release, documentation, cascade: this file only).
7
+ # The files share their hidden jobs with extends:, because YAML anchors do not cross the files of an include.
8
8
  #
9
9
  # All job names are prefixed js: to avoid any collision with PHP or custom
10
10
  # jobs when this template is combined with other templates.
11
- # pipeline-js-app.yml (fullstack context) includes this file directly — no duplication.
12
11
  #
13
12
  # USAGE in a consumer project:
14
- # ─────────────────────────────────────────
13
+ # ================
15
14
  # include:
16
15
  # - project: 'zairakai/npm-packages/js-dev-tools'
17
16
  # ref: main
18
17
  # file: '.gitlab/ci/pipeline-js-package.yml'
19
18
  #
20
19
  # variables:
21
- # CACHE_KEY: "my-package-v1"
20
+ # CACHE_KEY: "my-package-v2"
22
21
  # NPM_PACKAGE_NAME: "@myorg/my-package"
23
22
  #
24
23
  # FOR dev-tools ITSELF (self-hosted mode):
25
- # ─────────────────────────────────────────────────────
24
+ # ================
26
25
  # include:
27
26
  # - local: '.gitlab/ci/pipeline-js-package.yml'
28
27
  #
29
28
  # variables:
30
- # CACHE_KEY: "dev-tools-v1"
29
+ # CACHE_KEY: "dev-tools-v2"
31
30
  # NPM_PACKAGE_NAME: "@zairakai/js-dev-tools"
32
31
  # JS_DEV_TOOLS_SCRIPTS: "scripts"
33
- # ================================
34
32
 
35
33
  include:
36
- - template: Jobs/Secret-Detection.gitlab-ci.yml
34
+ # security.yml first: the template of the secret detection it includes sets variables that base.yml overrides.
35
+ - local: '.gitlab/ci/parts/security.yml'
36
+ - local: '.gitlab/ci/parts/base.yml'
37
+ - local: '.gitlab/ci/parts/quality.yml'
38
+ - local: '.gitlab/ci/parts/updates.yml'
39
+ - local: '.gitlab/ci/parts/publish.yml'
37
40
 
38
- # ================================
39
- # WORKFLOW
40
- # ================================
41
- workflow:
42
- rules:
43
- - if: $CI_COMMIT_TAG
44
- - if: $CI_PIPELINE_SOURCE == "schedule"
45
- - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
46
- - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
47
- - if: $CI_COMMIT_REF_NAME =~ /^feature\// || $CI_COMMIT_REF_NAME =~ /^fix\// || $CI_COMMIT_REF_NAME =~ /^hotfix\//
48
- - when: never
49
-
50
- # ================================
51
41
  # STAGES
52
- # ================================
42
+ # ================
53
43
  stages:
54
44
  - security
55
45
  - install
@@ -60,505 +50,10 @@ stages:
60
50
  - publish
61
51
  - release
62
52
 
63
- # ================================
64
- # RUNNERS
65
- # ================================
66
- # Every job runs on the self-hosted runner of the group, whatever the shared runners enabled on the project.
67
- # Only js:publish leaves it: npm trusted publishing does not accept a self-hosted runner.
68
- default:
69
- tags:
70
- - zairakai-ci
71
-
72
- # ================================
73
- # DEFAULT VARIABLES
74
- # ================================
53
+ # VARIABLES
54
+ # ================
75
55
  variables:
76
- # ── OVERRIDE PER PROJECT ──────────────────────────────────────────────────
77
- CACHE_KEY: "zairakai-npm-package"
78
- NPM_PACKAGE_NAME: "@zairakai/package"
79
-
80
- # Paths to dev-tools scripts.
81
- # Consumer projects do NOT need to override these.
82
- # dev-tools itself overrides them in its own .gitlab-ci.yml.
83
- JS_DEV_TOOLS_SCRIPTS: "node_modules/@zairakai/js-dev-tools/scripts"
84
-
85
- # ── NODE ──────────────────────────────────────────────────────────────────
86
- NODE_VERSION: "24"
87
- NODE_IMAGE: "zairakai/node:latest-dev"
88
- NODE_TEST_IMAGE: "zairakai/node:latest-test"
89
- # The jobs of the automatic updates sign with gpg: the image has it since 1.3.0. It is an exact version, published on
90
- # Docker Hub like our other images: the runner pulls it, whatever the old image it keeps locally.
91
- NODE_UPDATE_IMAGE: "zairakai/node:1.3.0-dev"
92
- SHELLCHECK_IMAGE: "koalaman/shellcheck-alpine:v0.10.0"
93
- RELEASE_CLI_IMAGE: "registry.gitlab.com/gitlab-org/release-cli:v0.18.0"
94
- ALPINE_IMAGE: "alpine:3.18"
95
-
96
- # ── GIT ───────────────────────────────────────────────────────────────────
97
- GIT_DEPTH: 1
98
- GIT_STRATEGY: fetch
99
- GIT_CLEAN_FLAGS: "-ffdx -e node_modules/ -e .npm/"
100
-
101
- # ── SECURITY ──────────────────────────────────────────────────────────────
102
- SECRET_DETECTION_EXCLUDED_PATHS: "node_modules/,dist/,build/,coverage/"
103
-
104
- # ================================
105
- # ANCHORS
106
- # ================================
107
- .base_job: &base_job
108
- retry:
109
- max: 2
110
- when:
111
- - runner_system_failure
112
- - stuck_or_timeout_failure
113
-
114
- .cache_node: &cache_node
115
- cache:
116
- key:
117
- files:
118
- - package-lock.json
119
- prefix: $CACHE_KEY
120
- paths:
121
- - node_modules/
122
- - .npm/
123
- policy: pull
124
-
125
- .cache_node_push: &cache_node_push
126
- cache:
127
- key:
128
- files:
129
- - package-lock.json
130
- prefix: $CACHE_KEY
131
- paths:
132
- - node_modules/
133
- - .npm/
134
- policy: pull-push
135
-
136
- .job_node: &job_node
137
- <<: [*base_job, *cache_node]
138
- image: ${NODE_IMAGE}
139
- before_script:
140
- - node --version
141
- - npm --version
142
-
143
- # ================================
144
- # SECURITY
145
- # ================================
146
- secret_detection:
147
- stage: security
148
- rules:
149
- - if: $UPDATE_DEPENDENCIES == "true"
150
- when: never
151
- - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
152
- - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
153
-
154
- # A tag whose format is not the one of VERSION_TAG_REGEX (group variable) fails here,
155
- # and the jobs that publish do not run for it.
156
- js:tag-format:
157
- <<: *base_job
158
- stage: security
159
- image: ${ALPINE_IMAGE}
160
- rules:
161
- - if: $UPDATE_DEPENDENCIES == "true"
162
- when: never
163
- - if: $CI_COMMIT_TAG
164
- script:
165
- - |
166
- regex="${VERSION_TAG_REGEX:-}"
167
- regex="${regex#/}"
168
- regex="${regex%/}"
169
- if [ -z "$regex" ]; then
170
- echo "ERROR: VERSION_TAG_REGEX is not set. It is a variable of the zairakai group."
171
- exit 1
172
- fi
173
- if ! printf '%s\n' "$CI_COMMIT_TAG" | grep -Eq "$regex"; then
174
- echo "ERROR: the tag \"$CI_COMMIT_TAG\" does not match $VERSION_TAG_REGEX (X.Y.Z or X.Y.Z-prerelease)."
175
- exit 1
176
- fi
177
- echo "Tag $CI_COMMIT_TAG: format OK"
178
-
179
- # ================================
180
- # INSTALL
181
- # ================================
182
- js:install:
183
- <<: [*base_job, *cache_node_push]
184
- stage: install
185
- rules:
186
- - if: $UPDATE_DEPENDENCIES == "true"
187
- when: never
188
- - when: on_success
189
- image: ${NODE_IMAGE}
190
- script:
191
- - npm ci --cache .npm --prefer-offline
192
- - |
193
- if [ -f /lib/ld-musl-x86_64.so.1 ]; then
194
- npm install --no-save @oxc-resolver/binding-linux-x64-musl @rollup/rollup-linux-x64-musl
195
- fi
196
- artifacts:
197
- paths:
198
- - node_modules/
199
- expire_in: 1 hour
200
-
201
- # ================================
202
- # VALIDATE
203
- # ================================
204
- js:validate:markdownlint:
205
- <<: [*base_job, *cache_node]
206
- stage: validate
207
- rules:
208
- - if: $UPDATE_DEPENDENCIES == "true"
209
- when: never
210
- - when: on_success
211
- image: ${NODE_IMAGE}
212
- script:
213
- - bash "$JS_DEV_TOOLS_SCRIPTS/markdownlint.sh"
214
-
215
- js:validate:shellcheck:
216
- <<: *base_job
217
- stage: validate
218
- rules:
219
- - if: $UPDATE_DEPENDENCIES == "true"
220
- when: never
221
- - when: on_success
222
- image: ${SHELLCHECK_IMAGE}
223
- before_script:
224
- - apk add --no-cache bash
225
- script:
226
- - |
227
- if [[ -d scripts/ ]]; then
228
- bash "$JS_DEV_TOOLS_SCRIPTS/validate-shellcheck.sh"
229
- else
230
- echo "No scripts/ directory found — skipping ShellCheck"
231
- fi
232
-
233
- # ================================
234
- # QUALITY
235
- # ================================
236
- js:quality:lint:
237
- <<: *job_node
238
- stage: quality
239
- rules:
240
- - if: $UPDATE_DEPENDENCIES == "true"
241
- when: never
242
- - when: on_success
243
- script:
244
- - bash "$JS_DEV_TOOLS_SCRIPTS/eslint.sh"
245
- artifacts:
246
- reports:
247
- junit: build/reports/eslint.xml
248
- paths:
249
- - build/reports/
250
- expire_in: 1 week
251
- when: always
252
-
253
- js:quality:format:
254
- <<: *job_node
255
- stage: quality
256
- rules:
257
- - if: $UPDATE_DEPENDENCIES == "true"
258
- when: never
259
- - when: on_success
260
- script:
261
- - bash "$JS_DEV_TOOLS_SCRIPTS/prettier.sh"
262
-
263
- js:quality:stylelint:
264
- <<: *job_node
265
- stage: quality
266
- rules:
267
- - if: $UPDATE_DEPENDENCIES == "true"
268
- when: never
269
- - when: on_success
270
- script:
271
- - bash "$JS_DEV_TOOLS_SCRIPTS/stylelint.sh"
272
-
273
- js:quality:typecheck:
274
- <<: *job_node
275
- stage: quality
276
- rules:
277
- - if: $UPDATE_DEPENDENCIES == "true"
278
- when: never
279
- - when: on_success
280
- script:
281
- - |
282
- if [ -f tsconfig.json ] && [ -f node_modules/.bin/tsc ]; then
283
- bash "$JS_DEV_TOOLS_SCRIPTS/typecheck.sh"
284
- else
285
- echo "TypeScript not configured — skipping (add tsconfig.json + typescript to devDependencies)"
286
- fi
287
-
288
- js:quality:knip:
289
- <<: *job_node
290
- stage: quality
291
- rules:
292
- - if: $UPDATE_DEPENDENCIES == "true"
293
- when: never
294
- - when: on_success
295
- script:
296
- - bash "$JS_DEV_TOOLS_SCRIPTS/knip.sh"
297
-
298
- js:quality:bats:
299
- <<: [*base_job, *cache_node]
300
- stage: quality
301
- rules:
302
- - if: $UPDATE_DEPENDENCIES == "true"
303
- when: never
304
- - when: on_success
305
- image: ${ALPINE_IMAGE}
306
- before_script:
307
- - apk add --no-cache bash bats git
308
- script:
309
- - |
310
- if [[ -d tests/bats ]]; then
311
- bats tests/bats --recursive
312
- else
313
- echo "No BATS tests found — skipping"
314
- fi
315
-
316
- js:quality:outdated:
317
- <<: *job_node
318
- stage: quality
319
- rules:
320
- - if: $UPDATE_DEPENDENCIES == "true"
321
- when: never
322
- - if: $CI_PIPELINE_SOURCE == "schedule"
323
- script:
324
- - bash "$JS_DEV_TOOLS_SCRIPTS/outdated.sh"
325
- artifacts:
326
- paths:
327
- - build/reports/npm-outdated.json
328
- expire_in: 1 week
329
- when: always
330
-
331
- # ================================
332
- # TEST
333
- # ================================
334
- js:test:
335
- <<: [*base_job, *cache_node]
336
- stage: test
337
- rules:
338
- - if: $UPDATE_DEPENDENCIES == "true"
339
- when: never
340
- - when: on_success
341
- image: ${NODE_TEST_IMAGE}
342
- script:
343
- - CI=true bash "$JS_DEV_TOOLS_SCRIPTS/test.sh"
344
- coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
345
- artifacts:
346
- reports:
347
- junit: build/coverage/junit.xml
348
- coverage_report:
349
- coverage_format: cobertura
350
- path: build/coverage/cobertura-coverage.xml
351
- paths:
352
- - build/coverage/
353
- expire_in: 1 week
354
- when: always
355
-
356
- # ================================
357
- # BUILD
358
- # ================================
359
- js:build:
360
- <<: *job_node
361
- stage: build
362
- script:
363
- - |
364
- if { [ -f node_modules/.bin/tsup ] || [ -f node_modules/.bin/tsc ]; } && [ -f tsconfig.json ]; then
365
- bash "$JS_DEV_TOOLS_SCRIPTS/build.sh"
366
- else
367
- echo "No TypeScript builder configured — skipping (install tsup or typescript)"
368
- fi
369
- artifacts:
370
- paths:
371
- - dist/
372
- expire_in: 1 week
373
- when: on_success
374
- rules:
375
- - if: $UPDATE_DEPENDENCIES == "true"
376
- when: never
377
- - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
378
- - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_BRANCH == "develop"
379
- - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_MERGE_REQUEST_ID
380
-
381
- # ================================
382
- # PUBLISH
383
- # ================================
384
- js:publish:
385
- <<: [*base_job, *cache_node]
386
- stage: publish
387
- image: ${NODE_IMAGE}
388
- # Trusted publishing: npm trusts this project and this job, and the OIDC token below authenticates the publication.
389
- # No npm token is stored anywhere. npm accepts only the shared runners of GitLab.com (not a self-hosted runner),
390
- # so this job is the only one that uses them. The tag is the one of GitLab, it cannot be renamed.
391
- tags:
392
- - saas-linux-small-amd64
393
- id_tokens:
394
- NPM_ID_TOKEN:
395
- aud: "npm:registry.npmjs.org"
396
- # Lets npm sign the provenance: the package page shows it was built on GitLab from this project.
397
- SIGSTORE_ID_TOKEN:
398
- aud: sigstore
399
- rules:
400
- - if: $UPDATE_DEPENDENCIES == "true"
401
- when: never
402
- - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
403
- script:
404
- - |
405
- # A pre-release (2.3.0-rc.1) goes to the npm tag "next", so it never becomes "latest"
406
- npm_tag="latest"
407
- if [[ $CI_COMMIT_TAG == *-* ]]; then
408
- npm_tag="next"
409
- fi
410
- echo "Publishing ${NPM_PACKAGE_NAME}@${CI_COMMIT_TAG} to npm (tag ${npm_tag})..."
411
- npm version "${CI_COMMIT_TAG}" --no-git-tag-version --allow-same-version
412
- npm publish --provenance --access public --tag "${npm_tag}"
413
- environment:
414
- name: production
415
- url: https://www.npmjs.com/package/${NPM_PACKAGE_NAME}
416
-
417
- # ================================
418
- # RELEASE
419
- # ================================
420
- js:release:
421
- <<: *base_job
422
- stage: release
423
- image: ${RELEASE_CLI_IMAGE}
424
- rules:
425
- - if: $UPDATE_DEPENDENCIES == "true"
426
- when: never
427
- - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
428
- before_script:
429
- - apk add --no-cache bash git jq
430
- - git config --global --add safe.directory '*'
431
- - git config --global user.name "GitLab CI"
432
- - git config --global user.email "ci@gitlab.com"
433
- script:
434
- - |
435
- # Tags are listed newest first, with or without the old "v" prefix (v2.1.0 then 2.2.0)
436
- PREVIOUS_TAG=$(git tag | sed -E 's/^v?(.*)$/\1 &/' | sort -k1,1 -Vr | cut -d' ' -f2 | grep -A1 -Fx "${CI_COMMIT_TAG}" | tail -n 1 || echo "")
437
- if [[ -n "$PREVIOUS_TAG" && "$PREVIOUS_TAG" != "$CI_COMMIT_TAG" ]]; then
438
- COMMITS=$(git log --pretty=format:"- %s" "${PREVIOUS_TAG}..${CI_COMMIT_TAG}" | head -20)
439
- else
440
- COMMITS="- Initial release"
441
- fi
442
- cat > release_notes.md << NOTES
443
- ## ${CI_COMMIT_TAG}
444
-
445
- ${COMMITS}
446
- NOTES
447
- release-cli create \
448
- --tag-name "${CI_COMMIT_TAG}" \
449
- --name "Release ${CI_COMMIT_TAG}" \
450
- --description "$(cat release_notes.md)" \
451
- --assets-link "{\"name\":\"npm\",\"url\":\"https://www.npmjs.com/package/${NPM_PACKAGE_NAME}/v/${CI_COMMIT_TAG}\"}"
452
- artifacts:
453
- paths:
454
- - release_notes.md
455
- expire_in: 1 year
456
-
457
- # ================================
458
- # DOCUMENTATION
459
- # ================================
460
- # The documentation site (GitLab Pages): every released version, each built from its own tag, and next, with a version
461
- # selector. See docs/scripts/publish.sh in the project. It comes with the release: a tag is always a release of main, and
462
- # nothing is published if the publication failed. The dependencies are the ones installed once by js:install.
463
- # A project without docs/scripts/publish.sh has no site.
464
- pages:
465
- <<: [*base_job, *cache_node]
466
- stage: release
467
- image: ${NODE_IMAGE}
468
- needs:
469
- - job: js:install
470
- - job: js:publish
471
- variables:
472
- GIT_DEPTH: 0
473
- before_script:
474
- - node --version
475
- script:
476
- - bash docs/scripts/publish.sh
477
- # The next jobs of the runner must not find (and lint) the docs dependencies or what they generate.
478
- after_script:
479
- - rm -rf docs/node_modules docs/.vitepress/dist docs/.vitepress/cache
480
- - git clean -fdXq docs || true
481
- artifacts:
482
- paths:
483
- - public
484
- expire_in: 1 week
485
- rules:
486
- - if: $UPDATE_DEPENDENCIES == "true"
487
- when: never
488
- - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
489
- exists:
490
- - docs/scripts/publish.sh
491
-
492
- # ================================
493
- # AUTOMATIC UPDATES
494
- # ================================
495
- # See the handbook, policies/dependency-management.md. The exceptions of a project live in .dependency-update.json.
496
- # The group variable GITLAB_TOKEN (protected, so these jobs run on main, develop and the tags) opens the merge requests,
497
- # merges them and creates the tags. The pipeline of each merge request is the gate: nothing is tested by these jobs.
498
-
499
- # A weekly schedule (or a pipeline started by the cascade) with UPDATE_DEPENDENCIES=true prepares the update.
500
- deps:update:
501
- <<: *base_job
502
- stage: install
503
- image: ${NODE_UPDATE_IMAGE}
504
- needs: []
505
- script:
506
- - node --version
507
- - "[ -d node_modules ] || npm ci --no-audit --no-fund"
508
- - '[ "${JS_DEV_TOOLS_SCRIPTS}" = "scripts" ] || npm install --no-save --no-audit --no-fund "@zairakai/js-dev-tools@latest"'
509
- - node "${JS_DEV_TOOLS_SCRIPTS}/update-dependencies.mjs" update
510
- rules:
511
- - if: $UPDATE_DEPENDENCIES == "true" && $AUDIT_DEPENDENCIES != "true" && $CI_COMMIT_BRANCH == "develop"
512
-
513
- # A daily schedule with UPDATE_DEPENDENCIES=true and AUDIT_DEPENDENCIES=true looks for security advisories: one issue per
514
- # advisory (ntfy alert, closed when it is gone) and, with the group variable AUTO_FIX=true, an update started to fix it.
515
- # The token FRESHNESS_TOKEN of the group (else GITLAB_TOKEN) opens the issues and starts the update; NTFY_URL is the alert.
516
- deps:audit:
517
- <<: *base_job
518
- stage: install
519
- image: ${NODE_UPDATE_IMAGE}
520
- needs: []
521
- script:
522
- - node --version
523
- - "[ -d node_modules ] || npm ci --no-audit --no-fund"
524
- - '[ "${JS_DEV_TOOLS_SCRIPTS}" = "scripts" ] || npm install --no-save --no-audit --no-fund "@zairakai/js-dev-tools@latest"'
525
- - node "${JS_DEV_TOOLS_SCRIPTS}/update-dependencies.mjs" audit
526
- rules:
527
- - if: $UPDATE_DEPENDENCIES == "true" && $AUDIT_DEPENDENCIES == "true" && $CI_COMMIT_BRANCH == "develop"
528
-
529
- # After the merge of an update into develop, bring develop into main.
530
- deps:release:
531
- <<: *base_job
532
- stage: release
533
- image: ${NODE_IMAGE}
534
- script:
535
- - "[ -d node_modules ] || npm ci --no-audit --no-fund"
536
- - node "${JS_DEV_TOOLS_SCRIPTS}/update-dependencies.mjs" release
537
- rules:
538
- - if: $CI_COMMIT_BRANCH == "develop" && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_MESSAGE =~ /chore\/update-dependencies/
539
-
540
- # After the merge of an update into main, tag it when a published range changed. The tag starts the publication.
541
- deps:tag:
542
- <<: *base_job
543
- stage: release
544
- image: ${NODE_UPDATE_IMAGE}
545
- variables:
546
- GIT_DEPTH: 0
547
- script:
548
- - "[ -d node_modules ] || npm ci --no-audit --no-fund"
549
- - node "${JS_DEV_TOOLS_SCRIPTS}/update-dependencies.mjs" tag
550
- rules:
551
- - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
552
-
553
- # After the publication, start the update of the projects that use this package (only if the project has a cascade).
554
- deps:cascade:
555
- <<: *base_job
556
- stage: release
557
- image: ${NODE_IMAGE}
558
- needs:
559
- - job: js:publish
560
- script:
561
- - "[ -d node_modules ] || npm ci --no-audit --no-fund"
562
- - node "${JS_DEV_TOOLS_SCRIPTS}/update-dependencies.mjs" cascade
563
- rules:
564
- - if: $CI_COMMIT_TAG =~ $VERSION_TAG_REGEX
56
+ # OVERRIDE PER PROJECT
57
+ # ================
58
+ CACHE_KEY: 'zairakai-npm-package'
59
+ NPM_PACKAGE_NAME: '@zairakai/package'
package/README.md CHANGED
@@ -1,9 +1,15 @@
1
- # @zairakai/js-dev-tools
1
+ # JS Dev Tools
2
+
3
+ ![JS Dev Tools](https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/raw/main/assets/banner.png)
4
+
5
+ `@zairakai/js-dev-tools`
2
6
 
3
7
  [![Main][pipeline-main-badge]][pipeline-main-link]
4
8
  [![Develop][pipeline-develop-badge]][pipeline-develop-link]
9
+ [![Coverage][coverage-badge]][pipeline-main-link]
5
10
 
6
11
  [![npm][npm-badge]][npm-link]
12
+ [![Base][base-badge]][base]
7
13
  [![Docs][docs-badge]][docs]
8
14
  [![GitLab Release][gitlab-release-badge]][gitlab-release]
9
15
  [![License][license-badge]][license]
@@ -12,8 +18,10 @@
12
18
  [![ESLint][eslint-badge]][eslint]
13
19
  [![Prettier][prettier-badge]][prettier]
14
20
  [![Stylelint][stylelint-badge]][stylelint]
21
+ [![Vitest][vitest-badge]][vitest]
22
+ [![Knip][knip-badge]][knip]
15
23
 
16
- One unified toolkit to set up JavaScript/TypeScript quality tooling. Context-aware by default — it adapts to both standalone packages and full-stack applications.
24
+ One unified toolkit to set up JavaScript/TypeScript quality tooling. Context-aware by default: it adapts to both standalone packages and full-stack applications.
17
25
 
18
26
  **Documentation: [js-dev-tools-3fa149.gitlab.io][docs]**
19
27
 
@@ -40,7 +48,7 @@ One unified toolkit to set up JavaScript/TypeScript quality tooling. Context-awa
40
48
  | **Prettier** | Opinionated formatter with SCSS and Tailwind support. |
41
49
  | **Stylelint** | SCSS linting with modern property ordering. |
42
50
  | **Markdownlint** | Consistent Markdown across all documentation. |
43
- | **Vitest** | Unit testing with v8 coverage. |
51
+ | **Vitest** | Unit testing with v8 coverage: 75 % required, 90 % as the good level. |
44
52
  | **Knip** | Dead code and unused dependency detection. |
45
53
  | **TypeScript** | Shared `tsconfig.base.json` for strict mode builds. |
46
54
  | **GitLab CI** | Reusable pipeline templates for npm packages and Laravel full-stack. |
@@ -93,6 +101,8 @@ make ci # full pipeline simulation
93
101
  make doctor # environment diagnostics
94
102
  ```
95
103
 
104
+ The same checks are npm scripts, for the projects that prefer them: `npm run quality`, `npm run quality:fix`, and one per tool (`eslint`, `prettier`, `stylelint`, `markdownlint`, `knip`, each with `:fix` when the tool can fix). They run the same scripts as `make`.
105
+
96
106
  ---
97
107
 
98
108
  ## Configuration
@@ -122,6 +132,22 @@ export default defineConfig({ ...baseConfig, test: { ...baseConfig.test } })
122
132
 
123
133
  ---
124
134
 
135
+ ## Tests and coverage
136
+
137
+ `make test-coverage` and the job `js:test` of the pipeline run Vitest with coverage. The reports are in `coverage/`: the HTML report, `lcov.info`, `cobertura-coverage.xml` (the coverage of the merge request) and `junit.xml` (the test report of the merge request). The base requires 75 % of the lines, functions, branches and statements, and shows 90 % as the good level. A project that is below lowers the threshold in its own file, and raises it again as it adds tests:
138
+
139
+ ```js
140
+ // vitest.config.js
141
+ import baseConfig from '@zairakai/js-dev-tools/vitest'
142
+ import { defineConfig, mergeConfig } from 'vitest/config'
143
+
144
+ export default mergeConfig(baseConfig, defineConfig({ test: { coverage: { thresholds: { lines: 60 } } } }))
145
+ ```
146
+
147
+ The tests do not use globals: `describe`, `it` and `expect` are imported from `vitest`. `coverage/` is ignored by Git and by the tools.
148
+
149
+ ---
150
+
125
151
  ## Publishing configs
126
152
 
127
153
  Publish individual config files to `config/dev-tools/` (never overwritten unless `--force`):
@@ -160,14 +186,24 @@ include:
160
186
  file: '.gitlab/ci/pipeline-js-package.yml'
161
187
 
162
188
  variables:
163
- CACHE_KEY: "my-package-v1"
189
+ CACHE_KEY: "my-package-v2"
164
190
  NPM_PACKAGE_NAME: "@myorg/my-package"
165
191
  ```
166
192
 
167
193
  Available templates:
168
194
 
169
- - `.gitlab/ci/pipeline-js-package.yml` — security → install → validate → quality → test → build → publish → release
170
- - `.gitlab/ci/pipeline-js-app.yml` — JS quality + test jobs for Laravel full-stack apps
195
+ - `.gitlab/ci/pipeline-js-package.yml`: security → install → validate → quality → test → build → publish → release
196
+ - `.gitlab/ci/pipeline-js-app.yml`: JS quality + test jobs for Laravel full-stack apps
197
+
198
+ Both files are entry points: the jobs are in `.gitlab/ci/parts/`, one file per role, and the application includes the parts it needs and none of what only a package does.
199
+
200
+ | Part | Jobs | Package | Application |
201
+ | :--- | :--- | :---: | :---: |
202
+ | `base.yml` | workflow, runner, variables, hidden jobs | yes | yes |
203
+ | `security.yml` | secret detection, check of the tag | yes | yes |
204
+ | `quality.yml` | install, validate, quality, test | yes | yes |
205
+ | `updates.yml` | `deps:update`, `deps:audit`, `deps:release`, `deps:tag` | yes | yes |
206
+ | `publish.yml` | build, publish, release, documentation, `deps:cascade` | yes | no |
171
207
 
172
208
  ---
173
209
 
@@ -205,6 +241,8 @@ make bats # shell script tests only
205
241
  make doctor # environment diagnostics
206
242
  ```
207
243
 
244
+ `make quality` may print a Knip hint: `Remove @vitest/coverage-v8 from ignoreDependencies`. It is a hint, not an error, and the entry stays: the projects whose Vitest config names the provider as a text (`provider: 'v8'`) inherit the list, and Knip cannot link that text to the package.
245
+
208
246
  ---
209
247
 
210
248
  ## Getting Help
@@ -246,4 +284,11 @@ make doctor # environment diagnostics
246
284
  [ecosystem]: https://gitlab.com/zairakai
247
285
  [docs]: https://js-dev-tools-3fa149.gitlab.io
248
286
  [docs-badge]: https://img.shields.io/badge/docs-online-blue
287
+ [coverage-badge]: https://gitlab.com/zairakai/npm-packages/js-dev-tools/badges/main/coverage.svg?job=js:test&key_text=Coverage
288
+ [base-badge]: https://img.shields.io/npm/dependency-version/@zairakai/js-dev-tools/@stanislas-poisson/js-dev-tools?label=base
289
+ [base]: https://github.com/Stanislas-Poisson/js-dev-tools
290
+ [vitest-badge]: https://img.shields.io/badge/test-vitest-6E9F18.svg?logo=vitest
291
+ [vitest]: https://vitest.dev
292
+ [knip-badge]: https://img.shields.io/badge/dead%20code-knip-EC4899.svg
293
+ [knip]: https://knip.dev
249
294
  [stats-card]: https://gitlab.com/zairakai/gitlab-profile/-/raw/main/assets/projects/js-dev-tools.svg