@zairakai/js-dev-tools 3.21.0 → 3.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.editorconfig +6 -1
- package/README.md +49 -13
- package/config/.markdownlintignore +3 -4
- package/config/.prettierignore +11 -6
- package/config/.stylelintignore +13 -10
- package/config/knip.config.js +6 -2
- package/config/stylelint.config.js +1 -0
- package/package.json +20 -6
- package/scripts/stylelint-fix.sh +12 -5
- package/scripts/stylelint.sh +12 -5
- package/scripts/update-dependencies.mjs +504 -133
- package/stubs/githooks/commit-msg +7 -4
- package/stubs/style/stylelint.config.js.stub +7 -0
- package/tools/make/bats.mk +3 -3
- package/tools/make/core.mk +3 -3
- package/tools/make/quality.mk +2 -1
- package/tools/make/variables.mk +1 -1
package/.editorconfig
CHANGED
|
@@ -8,7 +8,12 @@ indent_style = space
|
|
|
8
8
|
insert_final_newline = true
|
|
9
9
|
trim_trailing_whitespace = true
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
# Google JavaScript Style Guide: 80 columns
|
|
12
|
+
[*.{cjs,cts,js,mjs,mts,ts}]
|
|
13
|
+
max_line_length = 80
|
|
14
|
+
|
|
15
|
+
# Google Shell Style Guide: 2 spaces, 80 columns
|
|
16
|
+
[*.{bash,bats,sh}]
|
|
12
17
|
indent_size = 2
|
|
13
18
|
max_line_length = 80
|
|
14
19
|
|
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://gitlab.com/zairakai/npm-packages/js-dev-tools/-/raw/main/assets/icon.png" alt="JS Dev Tools" width="160">
|
|
3
|
+
</p>
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
# JS Dev Tools
|
|
6
6
|
|
|
7
7
|
[![Main][pipeline-main-badge]][pipeline-main-link]
|
|
8
8
|
[![Develop][pipeline-develop-badge]][pipeline-develop-link]
|
|
@@ -45,14 +45,14 @@ One unified toolkit to set up JavaScript/TypeScript quality tooling. Context-awa
|
|
|
45
45
|
| Tool | Responsibility |
|
|
46
46
|
| :--- | :--- |
|
|
47
47
|
| **ESLint** | Flat config with TypeScript, Vue 3, and import rules. |
|
|
48
|
-
| **Prettier** |
|
|
49
|
-
| **Stylelint** | SCSS linting with
|
|
48
|
+
| **Prettier** | The defaults of Prettier (80 columns), with the PHP and Blade plugins and the sorting of the imports. |
|
|
49
|
+
| **Stylelint** | SCSS linting with the property order of the style guides, and `createStylelintConfig` to change it. |
|
|
50
50
|
| **Markdownlint** | Consistent Markdown across all documentation. |
|
|
51
|
-
| **Vitest** | Unit testing with v8 coverage
|
|
51
|
+
| **Vitest** | Unit testing with v8 coverage of every file of `src/`: 75 % required, 90 % as the good level. |
|
|
52
52
|
| **Knip** | Dead code and unused dependency detection. |
|
|
53
|
-
| **TypeScript** | Shared `tsconfig.base.json` for strict mode
|
|
53
|
+
| **TypeScript** | Shared `tsconfig.base.json` for TypeScript 6 and the web: strict mode, unchecked indexed access, isolated modules. |
|
|
54
54
|
| **GitLab CI** | Reusable pipeline templates for npm packages and Laravel full-stack. |
|
|
55
|
-
| **Git Hooks** | Automated quality checks and
|
|
55
|
+
| **Git Hooks** | Automated quality checks, ticket prefixing and a commit subject of 50 characters at most. |
|
|
56
56
|
| **Makefile** | Unified `make quality`, `make test`, `make ci` targets (delegated to core). |
|
|
57
57
|
| **Shell Scripts** | Automated setup and config publishing. |
|
|
58
58
|
|
|
@@ -109,6 +109,9 @@ The same checks are npm scripts, for the projects that prefer them: `npm run qua
|
|
|
109
109
|
|
|
110
110
|
Extend the shared configs in your project files:
|
|
111
111
|
|
|
112
|
+
<details>
|
|
113
|
+
<summary>Configuration examples for each tool</summary>
|
|
114
|
+
|
|
112
115
|
```js
|
|
113
116
|
// eslint.config.js
|
|
114
117
|
export { default } from '@zairakai/js-dev-tools/eslint'
|
|
@@ -130,11 +133,27 @@ export default defineConfig({ ...baseConfig, test: { ...baseConfig.test } })
|
|
|
130
133
|
{ "extends": "@zairakai/js-dev-tools/tsconfig" }
|
|
131
134
|
```
|
|
132
135
|
|
|
136
|
+
```js
|
|
137
|
+
// stylelint.config.js: to add, remove or move a property of the order
|
|
138
|
+
import { createStylelintConfig } from '@zairakai/js-dev-tools/stylelint'
|
|
139
|
+
|
|
140
|
+
export default createStylelintConfig({
|
|
141
|
+
properties: (list) => list.filter((property) => property !== 'float'),
|
|
142
|
+
})
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
</details>
|
|
146
|
+
|
|
133
147
|
---
|
|
134
148
|
|
|
135
149
|
## Tests and coverage
|
|
136
150
|
|
|
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
|
|
151
|
+
`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 coverage counts **every file of `src/`**, tested or not: a file that no test imports lowers it. The base requires 75 % of the lines, functions, branches and statements, and shows 90 % as the good level.
|
|
152
|
+
|
|
153
|
+
<details>
|
|
154
|
+
<summary>Lowering a threshold in a project</summary>
|
|
155
|
+
|
|
156
|
+
A project that is below lowers the threshold in its own file, and raises it again as it adds tests:
|
|
138
157
|
|
|
139
158
|
```js
|
|
140
159
|
// vitest.config.js
|
|
@@ -144,13 +163,18 @@ import { defineConfig, mergeConfig } from 'vitest/config'
|
|
|
144
163
|
export default mergeConfig(baseConfig, defineConfig({ test: { coverage: { thresholds: { lines: 60 } } } }))
|
|
145
164
|
```
|
|
146
165
|
|
|
166
|
+
</details>
|
|
167
|
+
|
|
147
168
|
The tests do not use globals: `describe`, `it` and `expect` are imported from `vitest`. `coverage/` is ignored by Git and by the tools.
|
|
148
169
|
|
|
149
170
|
---
|
|
150
171
|
|
|
151
172
|
## Publishing configs
|
|
152
173
|
|
|
153
|
-
Publish individual config files to `config/dev-tools/` (never overwritten unless `--force`)
|
|
174
|
+
Publish individual config files to `config/dev-tools/` (never overwritten unless `--force`). The setup also creates, at the root, the thin files that the editor extensions look for (`eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `vitest.config.mjs`, `.markdownlint.json`) and the copies of the ignore files; a file that the project already has is kept.
|
|
175
|
+
|
|
176
|
+
<details>
|
|
177
|
+
<summary>The publish commands</summary>
|
|
154
178
|
|
|
155
179
|
```bash
|
|
156
180
|
# All at once
|
|
@@ -172,6 +196,8 @@ bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=vite
|
|
|
172
196
|
bash node_modules/@zairakai/js-dev-tools/scripts/setup-project.sh --publish=tsconfig
|
|
173
197
|
```
|
|
174
198
|
|
|
199
|
+
</details>
|
|
200
|
+
|
|
175
201
|
---
|
|
176
202
|
|
|
177
203
|
## GitLab CI pipeline templates
|
|
@@ -197,6 +223,9 @@ Available templates:
|
|
|
197
223
|
|
|
198
224
|
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
225
|
|
|
226
|
+
<details>
|
|
227
|
+
<summary>The parts of the pipelines</summary>
|
|
228
|
+
|
|
200
229
|
| Part | Jobs | Package | Application |
|
|
201
230
|
| :--- | :--- | :---: | :---: |
|
|
202
231
|
| `base.yml` | workflow, runner, variables, hidden jobs | yes | yes |
|
|
@@ -205,12 +234,17 @@ Both files are entry points: the jobs are in `.gitlab/ci/parts/`, one file per r
|
|
|
205
234
|
| `updates.yml` | `deps:update`, `deps:audit`, `deps:release`, `deps:tag` | yes | yes |
|
|
206
235
|
| `publish.yml` | build, publish, release, documentation, `deps:cascade` | yes | no |
|
|
207
236
|
|
|
237
|
+
</details>
|
|
238
|
+
|
|
208
239
|
---
|
|
209
240
|
|
|
210
241
|
## Automatic updates
|
|
211
242
|
|
|
212
243
|
The pipeline template updates the dependencies of a project by itself, and this package starts the update of the projects that use it. The rules are in the handbook (`policies/dependency-management.md` and `policies/versioning.md`).
|
|
213
244
|
|
|
245
|
+
<details>
|
|
246
|
+
<summary>The rules of the automatic updates</summary>
|
|
247
|
+
|
|
214
248
|
- A weekly schedule with the variable `UPDATE_DEPENDENCIES=true`, or a pipeline started by the cascade, runs `deps:update`: it takes the **minor and patch** updates after a cooling period, opens a merge request into `develop` and merges it **when its pipeline succeeds**. Major versions are never applied.
|
|
215
249
|
- `deps:release` brings `develop` into `main` after such an update, and `deps:tag` tags `main` when a published range (`dependencies`, `peerDependencies`) changed. A project that changed only its development dependencies is not tagged: its published archive is the same.
|
|
216
250
|
- After the publication of a tag, `deps:cascade` waits for the version to be on the registry, then starts the update of the projects that have a `.dependency-update.json`.
|
|
@@ -232,6 +266,10 @@ The exceptions of a project live in `.dependency-update.json` at its root (every
|
|
|
232
266
|
|
|
233
267
|
`tag.when` is `runtime` (default), `always` or `never`, and `tag.level` is `patch` (default) or `minor`. Only the projects that others depend on need a `cascade`. The group variable `GITLAB_TOKEN` is used to open the merge requests and to tag.
|
|
234
268
|
|
|
269
|
+
</details>
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
235
273
|
## Development
|
|
236
274
|
|
|
237
275
|
```bash
|
|
@@ -241,8 +279,6 @@ make bats # shell script tests only
|
|
|
241
279
|
make doctor # environment diagnostics
|
|
242
280
|
```
|
|
243
281
|
|
|
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
|
-
|
|
246
282
|
---
|
|
247
283
|
|
|
248
284
|
## Getting Help
|
package/config/.prettierignore
CHANGED
|
@@ -1,19 +1,24 @@
|
|
|
1
|
+
# Folders
|
|
2
|
+
.nuxt/
|
|
3
|
+
.output/
|
|
4
|
+
# Laravel: the cache is not source
|
|
5
|
+
bootstrap/cache/
|
|
1
6
|
build/
|
|
2
7
|
coverage/
|
|
3
8
|
dist/
|
|
4
9
|
docs/
|
|
5
10
|
node_modules/
|
|
6
11
|
public/
|
|
12
|
+
# Laravel: the runtime files are not source
|
|
13
|
+
storage/
|
|
7
14
|
storybook-static/
|
|
8
15
|
vendor/
|
|
9
|
-
|
|
10
|
-
|
|
16
|
+
|
|
17
|
+
# Files
|
|
11
18
|
*.lock
|
|
19
|
+
# Markdown is formatted by markdownlint
|
|
12
20
|
*.md
|
|
13
21
|
*.min.css
|
|
14
22
|
*.min.js
|
|
23
|
+
# Reports of GitLab
|
|
15
24
|
gl-*.json
|
|
16
|
-
|
|
17
|
-
# Laravel: the runtime files and the cache are not source
|
|
18
|
-
storage/
|
|
19
|
-
bootstrap/cache/
|
package/config/.stylelintignore
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# Folders
|
|
2
|
+
.nuxt/
|
|
3
|
+
.output/
|
|
4
|
+
# Laravel: the cache is not source
|
|
5
|
+
bootstrap/cache/
|
|
4
6
|
build/
|
|
5
7
|
coverage/
|
|
6
|
-
|
|
8
|
+
dist/
|
|
9
|
+
docs/
|
|
10
|
+
node_modules/
|
|
7
11
|
public/
|
|
8
|
-
|
|
9
|
-
.output/
|
|
10
|
-
*.min.css
|
|
11
|
-
|
|
12
|
-
# Laravel: the runtime files and the cache are not source
|
|
12
|
+
# Laravel: the runtime files are not source
|
|
13
13
|
storage/
|
|
14
|
-
|
|
14
|
+
vendor/
|
|
15
|
+
|
|
16
|
+
# Files
|
|
17
|
+
*.min.css
|
package/config/knip.config.js
CHANGED
|
@@ -14,9 +14,13 @@ export default {
|
|
|
14
14
|
// "Referenced optional peerDependencies" is informational - stylelint is intentionally optional
|
|
15
15
|
exclude: ['optionalPeerDependencies'],
|
|
16
16
|
|
|
17
|
+
// The Stylelint rules come with @zairakai/js-dev-tools, which gives their absolute paths in the configuration: a project
|
|
18
|
+
// does not list them, so the plugin of Knip for Stylelint would report each of them as unlisted
|
|
19
|
+
stylelint: false,
|
|
20
|
+
|
|
17
21
|
ignoreDependencies: [
|
|
18
|
-
//
|
|
19
|
-
'
|
|
22
|
+
// The binary of Stylelint comes with @zairakai/js-dev-tools too; a project may list it or not
|
|
23
|
+
'stylelint',
|
|
20
24
|
|
|
21
25
|
// Optional peer dep bundled for consumers
|
|
22
26
|
'zod',
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zairakai/js-dev-tools",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"description": "The
|
|
3
|
+
"version": "3.22.0",
|
|
4
|
+
"description": "The development toolkit of the JavaScript and TypeScript projects for the web: shared ESLint, Prettier, Stylelint, Vitest, TypeScript and markdownlint rules, Knip, Makefile targets, Git hooks and GitLab CI pipeline templates",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dev-tools",
|
|
7
7
|
"toolkit",
|
|
@@ -15,7 +15,12 @@
|
|
|
15
15
|
"stylelint",
|
|
16
16
|
"vitest",
|
|
17
17
|
"knip",
|
|
18
|
-
"typescript"
|
|
18
|
+
"typescript",
|
|
19
|
+
"markdownlint",
|
|
20
|
+
"tsconfig",
|
|
21
|
+
"editorconfig",
|
|
22
|
+
"vue",
|
|
23
|
+
"scss"
|
|
19
24
|
],
|
|
20
25
|
"homepage": "https://js-dev-tools-3fa149.gitlab.io",
|
|
21
26
|
"bugs": {
|
|
@@ -103,12 +108,12 @@
|
|
|
103
108
|
"smol-toml": "1.9.0"
|
|
104
109
|
},
|
|
105
110
|
"dependencies": {
|
|
106
|
-
"@stanislas-poisson/js-dev-tools": "^
|
|
111
|
+
"@stanislas-poisson/js-dev-tools": "^3.1.0",
|
|
107
112
|
"eslint": "^10.14.0",
|
|
108
113
|
"markdownlint-cli2": "^0.24.0",
|
|
109
114
|
"prettier": "^3.9.10",
|
|
110
115
|
"semver": "^7.8.6",
|
|
111
|
-
"stylelint": "^
|
|
116
|
+
"stylelint": "^18.0.0"
|
|
112
117
|
},
|
|
113
118
|
"devDependencies": {
|
|
114
119
|
"@vitest/coverage-v8": "^5.1.0",
|
|
@@ -119,17 +124,26 @@
|
|
|
119
124
|
"zod": "^4.6.7"
|
|
120
125
|
},
|
|
121
126
|
"peerDependencies": {
|
|
127
|
+
"@vitest/coverage-v8": "^5.0.0",
|
|
122
128
|
"eslint": "^10.14.0",
|
|
123
129
|
"typedoc": "^0.28.0",
|
|
130
|
+
"typescript": "^6.0.0",
|
|
131
|
+
"vitest": "^5.0.0",
|
|
124
132
|
"zod": "^3.0.0 || ^4.0.0"
|
|
125
133
|
},
|
|
126
134
|
"peerDependenciesMeta": {
|
|
127
|
-
"
|
|
135
|
+
"@vitest/coverage-v8": {
|
|
128
136
|
"optional": true
|
|
129
137
|
},
|
|
130
138
|
"typedoc": {
|
|
131
139
|
"optional": true
|
|
132
140
|
},
|
|
141
|
+
"typescript": {
|
|
142
|
+
"optional": true
|
|
143
|
+
},
|
|
144
|
+
"vitest": {
|
|
145
|
+
"optional": true
|
|
146
|
+
},
|
|
133
147
|
"zod": {
|
|
134
148
|
"optional": true
|
|
135
149
|
}
|
package/scripts/stylelint-fix.sh
CHANGED
|
@@ -24,16 +24,23 @@ if [[ -n "$STYLELINT_CONFIG" ]]; then
|
|
|
24
24
|
fi
|
|
25
25
|
|
|
26
26
|
if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
|
|
27
|
-
STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss}"
|
|
27
|
+
STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss resources/**/*.css resources/**/*.vue}"
|
|
28
28
|
else
|
|
29
|
-
STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss}"
|
|
29
|
+
STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss src/**/*.css src/**/*.vue}"
|
|
30
30
|
fi
|
|
31
31
|
|
|
32
|
+
# STYLELINT_TARGET is a list of globs separated by spaces (one per file type: stylelint lints the style blocks of .vue)
|
|
33
|
+
read -r -a STYLELINT_PATTERNS <<< "$STYLELINT_TARGET"
|
|
34
|
+
STYLELINT_ABSOLUTE=()
|
|
35
|
+
for _pattern in "${STYLELINT_PATTERNS[@]}"; do
|
|
36
|
+
STYLELINT_ABSOLUTE+=("${PROJECT_ROOT}/${_pattern}")
|
|
37
|
+
done
|
|
38
|
+
|
|
32
39
|
log_step "Fixing: $STYLELINT_TARGET"
|
|
33
40
|
|
|
34
41
|
# Skip gracefully if no matching files exist
|
|
35
|
-
if ! has_files "${
|
|
36
|
-
log_info "No SCSS
|
|
42
|
+
if ! has_files "${STYLELINT_ABSOLUTE[@]}"; then
|
|
43
|
+
log_info "No SCSS, CSS or Vue files found matching ${STYLELINT_TARGET} - skipping"
|
|
37
44
|
exit 0
|
|
38
45
|
fi
|
|
39
46
|
|
|
@@ -60,6 +67,6 @@ if [[ ${#EXTRA_IGNORES[@]} -gt 0 ]]; then
|
|
|
60
67
|
STYLELINT_ARGS+=(--ignore-path "$_TMP_IGNORE")
|
|
61
68
|
fi
|
|
62
69
|
|
|
63
|
-
"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "$
|
|
70
|
+
"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "${STYLELINT_PATTERNS[@]}"
|
|
64
71
|
|
|
65
72
|
log_success "Stylelint fix applied"
|
package/scripts/stylelint.sh
CHANGED
|
@@ -26,16 +26,23 @@ fi
|
|
|
26
26
|
|
|
27
27
|
# Lint target depends on project type (overridable via env)
|
|
28
28
|
if [[ "$PROJECT_TYPE" == "laravel-app" ]]; then
|
|
29
|
-
STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss}"
|
|
29
|
+
STYLELINT_TARGET="${STYLELINT_TARGET:-resources/**/*.scss resources/**/*.css resources/**/*.vue}"
|
|
30
30
|
else
|
|
31
|
-
STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss}"
|
|
31
|
+
STYLELINT_TARGET="${STYLELINT_TARGET:-src/**/*.scss src/**/*.css src/**/*.vue}"
|
|
32
32
|
fi
|
|
33
33
|
|
|
34
|
+
# STYLELINT_TARGET is a list of globs separated by spaces (one per file type: stylelint lints the style blocks of .vue)
|
|
35
|
+
read -r -a STYLELINT_PATTERNS <<< "$STYLELINT_TARGET"
|
|
36
|
+
STYLELINT_ABSOLUTE=()
|
|
37
|
+
for _pattern in "${STYLELINT_PATTERNS[@]}"; do
|
|
38
|
+
STYLELINT_ABSOLUTE+=("${PROJECT_ROOT}/${_pattern}")
|
|
39
|
+
done
|
|
40
|
+
|
|
34
41
|
log_step "Checking: $STYLELINT_TARGET"
|
|
35
42
|
|
|
36
43
|
# Skip gracefully if no matching files exist (stylelint v16 errors on empty glob)
|
|
37
|
-
if ! has_files "${
|
|
38
|
-
log_info "No SCSS
|
|
44
|
+
if ! has_files "${STYLELINT_ABSOLUTE[@]}"; then
|
|
45
|
+
log_info "No SCSS, CSS or Vue files found matching ${STYLELINT_TARGET} - skipping"
|
|
39
46
|
exit 0
|
|
40
47
|
fi
|
|
41
48
|
|
|
@@ -62,6 +69,6 @@ if [[ ${#EXTRA_IGNORES[@]} -gt 0 ]]; then
|
|
|
62
69
|
STYLELINT_ARGS+=(--ignore-path "$_TMP_IGNORE")
|
|
63
70
|
fi
|
|
64
71
|
|
|
65
|
-
"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "$
|
|
72
|
+
"$STYLELINT_BIN" "${STYLELINT_ARGS[@]}" "${STYLELINT_PATTERNS[@]}"
|
|
66
73
|
|
|
67
74
|
log_success "Stylelint check passed"
|