@zairakai/js-dev-tools 3.15.0 → 3.16.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/README.md CHANGED
@@ -178,6 +178,7 @@ The pipeline template updates the dependencies of a project by itself, and this
178
178
  - 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.
179
179
  - `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.
180
180
  - 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`.
181
+ - The packages of the [dependency policy](https://gitlab.com/zairakai/dependency-policy) (`node.json`) are never updated. `node node_modules/@zairakai/js-dev-tools/scripts/update-dependencies.mjs policy-check <ref>` fails when the change since `<ref>` updates one of them in `package.json` or `package-lock.json`; it only reads, so it runs on GitHub as well.
181
182
 
182
183
  The same script serves the PHP projects (`composer.json`): a job in the PHP image runs `composer update`, then this script commits, signs and opens the merge request, and `deps:tag` looks at `require` only. The jobs that sign (`deps:update`, `deps:tag`) run on an exact version of the node image (`NODE_UPDATE_IMAGE`, published on Docker Hub), because they need `gpg` and the image of the runner is not updated by itself.
183
184
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zairakai/js-dev-tools",
3
- "version": "3.15.0",
3
+ "version": "3.16.0",
4
4
  "description": "The unified and centralized development toolkit for JavaScript/TypeScript projects - ESLint, Prettier, Stylelint, Knip, Vitest, Git Hooks, and GitLab CI pipeline templates",
5
5
  "keywords": [
6
6
  "dev-tools",
@@ -2,7 +2,7 @@
2
2
  /**
3
3
  * Automatic updates of the dependencies of a package of the zairakai group.
4
4
  *
5
- * Usage: node update-dependencies.mjs update | release | tag | cascade | audit | policy | policy-validate
5
+ * Usage: node update-dependencies.mjs update | release | tag | cascade | audit | policy | policy-validate | policy-check <ref>
6
6
  *
7
7
  * - update: prepare a branch with the minor and patch updates, open a merge request into develop and merge it when its
8
8
  * pipeline succeeds. The pipeline of the merge request is the gate: nothing is tested here.
@@ -11,9 +11,9 @@
11
11
  * - cascade: after the publication of this package, start the update of the projects that use it.
12
12
  * - audit: look for security advisories, open one issue per advisory and, with AUTO_FIX=true, start an update to fix them
13
13
  * (UPDATE_URGENT=true: the new versions are taken without waiting, and `npm audit fix` is run).
14
- * - policy: in the repository dependency-policy, lift the entries of node.json and php.json whose condition is met (merge
15
- * request).
14
+ * - policy: in the repository dependency-policy, lift the entries whose condition is met (merge request).
16
15
  * - policy-validate: in the repository dependency-policy, check the shape of the files.
16
+ * - policy-check: fail when the change since a ref updates a package of the policy (GitLab or GitHub, it only reads).
17
17
  *
18
18
  * The packages listed in the dependency policy (https://gitlab.com/zairakai/dependency-policy) are never updated, whatever
19
19
  * the project. DEPENDENCY_POLICY_URL replaces the address of the files.
@@ -253,77 +253,43 @@ export function isLifted(entry, ranges) {
253
253
  })
254
254
  }
255
255
 
256
- /** One token of a Composer constraint as semver reads it: only `~` differs (`~1.2` is `>=1.2.0 <2.0.0` for Composer). */
257
- function composerToken(token) {
258
- const tilde = /^~v?(\d+)(?:\.(\d+))?$/.exec(token)
256
+ /** The versions of every package of a package-lock.json, by name (a package installed twice has several). */
257
+ export function lockedVersions(lock) {
258
+ const versions = {}
259
259
 
260
- return tilde ? `>=${tilde[1]}.${tilde[2] ?? 0}.0 <${Number(tilde[1]) + 1}.0.0` : token
261
- }
262
-
263
- /**
264
- * A Composer constraint (`||` or `|`, comma or space, `~`, `^`, `*`, `@stable`) as a range that semver compares, or null
265
- * when it cannot be expressed (branches, `!=`, aliases): a peer whose range is not understood never lifts an entry.
266
- */
267
- export function composerRange(constraint) {
268
- if ('string' !== typeof constraint) return null
269
-
270
- const text = constraint.replace(/@\w+/g, '').trim()
271
- if ('' === text || /(^|[\s|,])dev-|\sas\s|!=/.test(text)) return null
272
-
273
- const alternatives = text.split(/\s*\|\|?\s*/).map((alternative) => {
274
- if (/\s-\s/.test(alternative)) return alternative.trim()
275
-
276
- return alternative.replaceAll(',', ' ').split(/\s+/).filter(Boolean).map(composerToken).join(' ')
277
- })
260
+ for (const [path, info] of Object.entries(lock?.packages ?? {})) {
261
+ if ('' === path || !info?.version) continue
278
262
 
279
- if (alternatives.includes('')) return null
280
-
281
- const range = alternatives.join(' || ')
263
+ const name = path.slice(path.lastIndexOf('node_modules/') + 'node_modules/'.length)
264
+ versions[name] = [...new Set([...(versions[name] ?? []), info.version])].sort()
265
+ }
282
266
 
283
- return null === semver.validRange(range) ? null : range
267
+ return versions
284
268
  }
285
269
 
286
- /** The releases of the metadata of Packagist (p2) in full: after the first one, each lists only what changed. */
287
- export function expandReleases(releases) {
288
- let previous = {}
289
-
290
- return releases.map((release) => {
291
- const full = { ...previous }
270
+ /**
271
+ * The packages of the policy whose version changes: a range of package.json or a locked version. A package that is
272
+ * added or removed is not an update.
273
+ */
274
+ export function policyViolations({ blocked, beforeManifest, afterManifest, beforeLock, afterLock }) {
275
+ const problems = []
292
276
 
293
- for (const [key, value] of Object.entries(release)) {
294
- if ('__unset' === value) delete full[key]
295
- else full[key] = value
277
+ for (const row of diffDependencies(beforeManifest, afterManifest)) {
278
+ if (blocked.includes(row.name) && null !== row.from && null !== row.to) {
279
+ problems.push(`package.json: ${row.name} moves from ${row.from} to ${row.to}.`)
296
280
  }
281
+ }
297
282
 
298
- previous = full
299
-
300
- return full
301
- })
302
- }
303
-
304
- /** The highest stable release, or null. */
305
- export function latestStable(releases) {
306
- let latest = null
307
- let latestVersion = null
308
-
309
- for (const release of releases) {
310
- const version = semver.valid(String(release.version ?? '').replace(/^v/, ''))
311
- if (null === version || null !== semver.prerelease(version)) continue
283
+ const before = lockedVersions(beforeLock)
284
+ const after = lockedVersions(afterLock)
312
285
 
313
- if (null === latestVersion || semver.gt(version, latestVersion)) {
314
- latest = release
315
- latestVersion = version
286
+ for (const name of blocked) {
287
+ if (before[name] && after[name] && before[name].join(', ') !== after[name].join(', ')) {
288
+ problems.push(`package-lock.json: ${name} moves from ${before[name].join(', ')} to ${after[name].join(', ')}.`)
316
289
  }
317
290
  }
318
291
 
319
- return latest
320
- }
321
-
322
- /** The range in which the latest stable release of a Composer package requires `name`, or null. */
323
- export function composerPeerRange(releases, name) {
324
- const constraint = latestStable(expandReleases(releases))?.require?.[name]
325
-
326
- return composerRange(constraint)
292
+ return problems
327
293
  }
328
294
 
329
295
  /**
@@ -1047,20 +1013,6 @@ function peerRange(peer, name) {
1047
1013
  }
1048
1014
  }
1049
1015
 
1050
- /** The range in which the latest release of the Composer package `peer` requires `name`, or null. */
1051
- export async function composerPeerRangeOnline(peer, name, fetchImpl = fetch) {
1052
- try {
1053
- const response = await fetchImpl(`https://repo.packagist.org/p2/${peer}.json`, {
1054
- signal: AbortSignal.timeout(20000),
1055
- })
1056
- if (!response.ok) return null
1057
-
1058
- return composerPeerRange((await response.json()).packages?.[peer] ?? [], name)
1059
- } catch {
1060
- return null
1061
- }
1062
- }
1063
-
1064
1016
  /** In the repository dependency-policy: check the shape of the files. */
1065
1017
  async function policyValidate() {
1066
1018
  let failed = false
@@ -1083,42 +1035,24 @@ async function policyValidate() {
1083
1035
  log('The dependency policy is valid.')
1084
1036
  }
1085
1037
 
1086
- /** The range in which the latest release of `peer` requires `name`, in the registry of the ecosystem. */
1087
- function peerRangeOf(ecosystem, peer, name) {
1088
- return 'npm' === ecosystem ? peerRange(peer, name) : composerPeerRangeOnline(peer, name)
1089
- }
1090
-
1091
1038
  /** In the repository dependency-policy: lift the entries whose condition is met, with a merge request into main. */
1092
1039
  async function policyWatch() {
1093
1040
  assertEnvironment()
1094
1041
 
1095
- const changes = []
1096
-
1097
- for (const [ecosystem, file] of Object.entries(POLICY_FILES)) {
1098
- if (!existsSync(file)) continue
1099
-
1100
- const doc = JSON.parse(readFileSync(file, 'utf8'))
1101
- const errors = validatePolicy(doc)
1102
- if (0 < errors.length) throw new Error(`${file} is not valid: ${errors.join(' ')}`)
1103
-
1104
- const lifted = []
1105
-
1106
- for (const entry of doc.entries) {
1107
- if (!entry.unblock) continue
1042
+ const file = POLICY_FILES.npm
1043
+ const doc = JSON.parse(readFileSync(file, 'utf8'))
1044
+ const errors = validatePolicy(doc)
1045
+ if (0 < errors.length) throw new Error(`${file} is not valid: ${errors.join(' ')}`)
1108
1046
 
1109
- const ranges = Object.fromEntries(
1110
- await Promise.all(
1111
- entry.unblock.peers.map(async (peer) => [peer, await peerRangeOf(ecosystem, peer, entry.package)])
1112
- )
1113
- )
1047
+ const lifted = doc.entries.filter((entry) => {
1048
+ if (!entry.unblock) return false
1114
1049
 
1115
- if (isLifted(entry, ranges)) lifted.push(entry)
1116
- }
1050
+ const ranges = Object.fromEntries(entry.unblock.peers.map((peer) => [peer, peerRange(peer, entry.package)]))
1117
1051
 
1118
- if (0 < lifted.length) changes.push({ file, doc, lifted })
1119
- }
1052
+ return isLifted(entry, ranges)
1053
+ })
1120
1054
 
1121
- if (0 === changes.length) {
1055
+ if (0 === lifted.length) {
1122
1056
  log('No entry can be lifted.')
1123
1057
  return
1124
1058
  }
@@ -1128,22 +1062,17 @@ async function policyWatch() {
1128
1062
  return
1129
1063
  }
1130
1064
 
1131
- const all = changes.flatMap(({ lifted }) => lifted)
1132
- const names = all.map((entry) => entry.package).join(', ')
1065
+ const names = lifted.map((entry) => entry.package).join(', ')
1133
1066
  const branch = `${POLICY_BRANCH_PREFIX}-${new Date().toISOString().slice(0, 10).replaceAll('-', '')}`
1134
1067
  const subject = `chore(policy): unblock ${names}`
1135
1068
 
1136
1069
  configureSigning()
1137
1070
  run('git', ['switch', '-C', branch])
1138
-
1139
- for (const { file, doc, lifted } of changes) {
1140
- writeFileSync(
1141
- file,
1142
- `${JSON.stringify({ ...doc, entries: doc.entries.filter((entry) => !lifted.includes(entry)) }, null, 2)}\n`
1143
- )
1144
- run('git', ['add', file])
1145
- }
1146
-
1071
+ writeFileSync(
1072
+ file,
1073
+ `${JSON.stringify({ ...doc, entries: doc.entries.filter((entry) => !lifted.includes(entry)) }, null, 2)}\n`
1074
+ )
1075
+ run('git', ['add', file])
1147
1076
  run('git', ['commit', '-m', subject, '-m', 'The peer ranges of the packages that held it back now accept it.'])
1148
1077
  run('git', ['push', remoteUrl(), `HEAD:refs/heads/${branch}`])
1149
1078
 
@@ -1151,7 +1080,7 @@ async function policyWatch() {
1151
1080
  source_branch: branch,
1152
1081
  target_branch: 'main',
1153
1082
  title: subject,
1154
- description: `The condition of the entry is met: ${all.map((entry) => `${entry.package} ${entry.unblock.version} (${entry.unblock.peers.join(', ')})`).join('; ')}. It is merged when its pipeline succeeds, and the update tools take the package at their next run.`,
1083
+ description: `The condition of the entry is met: ${lifted.map((entry) => `${entry.package} ${entry.unblock.version} (${entry.unblock.peers.join(', ')})`).join('; ')}. It is merged when its pipeline succeeds, and the update tools take the package at their next run.`,
1155
1084
  remove_source_branch: true,
1156
1085
  ...(await mergeRequestOptions()),
1157
1086
  })
@@ -1163,9 +1092,46 @@ async function policyWatch() {
1163
1092
  await mergeWhenGreen(request.data.iid)
1164
1093
  }
1165
1094
 
1166
- const modes = { update, release, tag, cascade, audit, policy: policyWatch, 'policy-validate': policyValidate }
1095
+ /** Fail when the working tree updates a package of the policy compared with `base`: a range or a locked version. */
1096
+ async function policyCheck(_config, base) {
1097
+ if (!base) throw new Error('Usage: node update-dependencies.mjs policy-check <ref>')
1098
+
1099
+ const blocked = (await readPolicy('npm')).entries.map((entry) => entry.package)
1100
+ const atBase = (file) => {
1101
+ try {
1102
+ return JSON.parse(capture('git', ['show', `${base}:${file}`]))
1103
+ } catch {
1104
+ return null
1105
+ }
1106
+ }
1107
+ const now = (file) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null)
1108
+
1109
+ const problems = policyViolations({
1110
+ blocked,
1111
+ beforeManifest: atBase('package.json'),
1112
+ afterManifest: now('package.json'),
1113
+ beforeLock: atBase('package-lock.json'),
1114
+ afterLock: now('package-lock.json'),
1115
+ })
1116
+
1117
+ for (const problem of problems) console.error(problem)
1118
+ if (0 < problems.length) throw new Error('The change updates a package that the dependency policy holds back.')
1119
+
1120
+ log('No package of the dependency policy is updated.')
1121
+ }
1122
+
1123
+ const modes = {
1124
+ update,
1125
+ release,
1126
+ tag,
1127
+ cascade,
1128
+ audit,
1129
+ policy: policyWatch,
1130
+ 'policy-validate': policyValidate,
1131
+ 'policy-check': policyCheck,
1132
+ }
1167
1133
 
1168
- async function main(mode) {
1134
+ async function main(mode, argument) {
1169
1135
  if (!modes[mode]) {
1170
1136
  console.error(
1171
1137
  'Usage: node update-dependencies.mjs update | release | tag | cascade | audit | policy | policy-validate'
@@ -1175,7 +1141,7 @@ async function main(mode) {
1175
1141
  }
1176
1142
 
1177
1143
  try {
1178
- await modes[mode](loadConfig())
1144
+ await modes[mode](loadConfig(), argument)
1179
1145
  } catch (error) {
1180
1146
  console.error(secret(error.message))
1181
1147
  process.exitCode = 1
@@ -1183,5 +1149,5 @@ async function main(mode) {
1183
1149
  }
1184
1150
 
1185
1151
  if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
1186
- await main(process.argv[2])
1152
+ await main(process.argv[2], process.argv[3])
1187
1153
  }