@zairakai/js-dev-tools 3.15.0 → 3.17.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,8 @@ 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.
182
+ - `dependabot-sync` rewrites the ignore rules of `.github/dependabot.yml`, between `# BEGIN dependency-policy (npm)` and `# END dependency-policy (npm)`, with one rule per package of the policy: the policy is the only place where a package is held back.
181
183
 
182
184
  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
185
 
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.17.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> | dependabot-sync
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,10 @@
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
+ * - dependabot-sync: rewrite the ignore rules of .github/dependabot.yml (between the markers of the ecosystem) from the policy.
17
18
  *
18
19
  * The packages listed in the dependency policy (https://gitlab.com/zairakai/dependency-policy) are never updated, whatever
19
20
  * the project. DEPENDENCY_POLICY_URL replaces the address of the files.
@@ -45,6 +46,7 @@ const ISSUE_LABELS = ['Kind::Security', 'Area::Security', 'Automated']
45
46
  const POLICY_URL = 'https://gitlab.com/zairakai/dependency-policy/-/raw/main'
46
47
  const POLICY_FILES = { npm: 'node.json', composer: 'php.json' }
47
48
  const POLICY_BRANCH_PREFIX = 'chore/unblock'
49
+ const DEPENDABOT_FILE = '.github/dependabot.yml'
48
50
  const GROUP_SCOPE = '@zairakai/'
49
51
  const TRUSTED_SCOPES = [GROUP_SCOPE, '@stanislas-poisson/']
50
52
 
@@ -253,77 +255,65 @@ export function isLifted(entry, ranges) {
253
255
  })
254
256
  }
255
257
 
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)
258
+ /** The versions of every package of a package-lock.json, by name (a package installed twice has several). */
259
+ export function lockedVersions(lock) {
260
+ const versions = {}
259
261
 
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
- })
278
-
279
- if (alternatives.includes('')) return null
262
+ for (const [path, info] of Object.entries(lock?.packages ?? {})) {
263
+ if ('' === path || !info?.version) continue
280
264
 
281
- const range = alternatives.join(' || ')
265
+ const name = path.slice(path.lastIndexOf('node_modules/') + 'node_modules/'.length)
266
+ versions[name] = [...new Set([...(versions[name] ?? []), info.version])].sort()
267
+ }
282
268
 
283
- return null === semver.validRange(range) ? null : range
269
+ return versions
284
270
  }
285
271
 
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 }
272
+ /**
273
+ * The packages of the policy whose version changes: a range of package.json or a locked version. A package that is
274
+ * added or removed is not an update.
275
+ */
276
+ export function policyViolations({ blocked, beforeManifest, afterManifest, beforeLock, afterLock }) {
277
+ const problems = []
292
278
 
293
- for (const [key, value] of Object.entries(release)) {
294
- if ('__unset' === value) delete full[key]
295
- else full[key] = value
279
+ for (const row of diffDependencies(beforeManifest, afterManifest)) {
280
+ if (blocked.includes(row.name) && null !== row.from && null !== row.to) {
281
+ problems.push(`package.json: ${row.name} moves from ${row.from} to ${row.to}.`)
296
282
  }
283
+ }
297
284
 
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
285
+ const before = lockedVersions(beforeLock)
286
+ const after = lockedVersions(afterLock)
312
287
 
313
- if (null === latestVersion || semver.gt(version, latestVersion)) {
314
- latest = release
315
- latestVersion = version
288
+ for (const name of blocked) {
289
+ if (before[name] && after[name] && before[name].join(', ') !== after[name].join(', ')) {
290
+ problems.push(`package-lock.json: ${name} moves from ${before[name].join(', ')} to ${after[name].join(', ')}.`)
316
291
  }
317
292
  }
318
293
 
319
- return latest
294
+ return problems
320
295
  }
321
296
 
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]
297
+ /**
298
+ * The text of dependabot.yml with the block of the ecosystem rewritten: between `# BEGIN dependency-policy (npm)` and
299
+ * `# END dependency-policy (npm)`, one ignore rule per package of the policy (nothing when none). Null without markers.
300
+ */
301
+ export function syncDependabot(text, names, ecosystem) {
302
+ const begin = `# BEGIN dependency-policy (${ecosystem})`
303
+ const end = `# END dependency-policy (${ecosystem})`
304
+ const pattern = new RegExp(
305
+ `^([ \\t]*)${begin.replaceAll(/[()]/g, '\\$&')}\\n[\\s\\S]*?^[ \\t]*${end.replaceAll(/[()]/g, '\\$&')}$`,
306
+ 'm'
307
+ )
308
+ const match = pattern.exec(text)
309
+
310
+ if (null === match) return null
325
311
 
326
- return composerRange(constraint)
312
+ const indent = match[1]
313
+ const rules =
314
+ 0 === names.length ? [] : [`${indent}ignore:`, ...names.map((name) => `${indent} - dependency-name: "${name}"`)]
315
+
316
+ return text.replace(pattern, () => [`${indent}${begin}`, ...rules, `${indent}${end}`].join('\n'))
327
317
  }
328
318
 
329
319
  /**
@@ -1047,20 +1037,6 @@ function peerRange(peer, name) {
1047
1037
  }
1048
1038
  }
1049
1039
 
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
1040
  /** In the repository dependency-policy: check the shape of the files. */
1065
1041
  async function policyValidate() {
1066
1042
  let failed = false
@@ -1083,42 +1059,24 @@ async function policyValidate() {
1083
1059
  log('The dependency policy is valid.')
1084
1060
  }
1085
1061
 
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
1062
  /** In the repository dependency-policy: lift the entries whose condition is met, with a merge request into main. */
1092
1063
  async function policyWatch() {
1093
1064
  assertEnvironment()
1094
1065
 
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(' ')}`)
1066
+ const file = POLICY_FILES.npm
1067
+ const doc = JSON.parse(readFileSync(file, 'utf8'))
1068
+ const errors = validatePolicy(doc)
1069
+ if (0 < errors.length) throw new Error(`${file} is not valid: ${errors.join(' ')}`)
1103
1070
 
1104
- const lifted = []
1071
+ const lifted = doc.entries.filter((entry) => {
1072
+ if (!entry.unblock) return false
1105
1073
 
1106
- for (const entry of doc.entries) {
1107
- if (!entry.unblock) continue
1074
+ const ranges = Object.fromEntries(entry.unblock.peers.map((peer) => [peer, peerRange(peer, entry.package)]))
1108
1075
 
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
- )
1114
-
1115
- if (isLifted(entry, ranges)) lifted.push(entry)
1116
- }
1117
-
1118
- if (0 < lifted.length) changes.push({ file, doc, lifted })
1119
- }
1076
+ return isLifted(entry, ranges)
1077
+ })
1120
1078
 
1121
- if (0 === changes.length) {
1079
+ if (0 === lifted.length) {
1122
1080
  log('No entry can be lifted.')
1123
1081
  return
1124
1082
  }
@@ -1128,22 +1086,17 @@ async function policyWatch() {
1128
1086
  return
1129
1087
  }
1130
1088
 
1131
- const all = changes.flatMap(({ lifted }) => lifted)
1132
- const names = all.map((entry) => entry.package).join(', ')
1089
+ const names = lifted.map((entry) => entry.package).join(', ')
1133
1090
  const branch = `${POLICY_BRANCH_PREFIX}-${new Date().toISOString().slice(0, 10).replaceAll('-', '')}`
1134
1091
  const subject = `chore(policy): unblock ${names}`
1135
1092
 
1136
1093
  configureSigning()
1137
1094
  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
-
1095
+ writeFileSync(
1096
+ file,
1097
+ `${JSON.stringify({ ...doc, entries: doc.entries.filter((entry) => !lifted.includes(entry)) }, null, 2)}\n`
1098
+ )
1099
+ run('git', ['add', file])
1147
1100
  run('git', ['commit', '-m', subject, '-m', 'The peer ranges of the packages that held it back now accept it.'])
1148
1101
  run('git', ['push', remoteUrl(), `HEAD:refs/heads/${branch}`])
1149
1102
 
@@ -1151,7 +1104,7 @@ async function policyWatch() {
1151
1104
  source_branch: branch,
1152
1105
  target_branch: 'main',
1153
1106
  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.`,
1107
+ 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
1108
  remove_source_branch: true,
1156
1109
  ...(await mergeRequestOptions()),
1157
1110
  })
@@ -1163,9 +1116,70 @@ async function policyWatch() {
1163
1116
  await mergeWhenGreen(request.data.iid)
1164
1117
  }
1165
1118
 
1166
- const modes = { update, release, tag, cascade, audit, policy: policyWatch, 'policy-validate': policyValidate }
1119
+ /** Fail when the working tree updates a package of the policy compared with `base`: a range or a locked version. */
1120
+ async function policyCheck(_config, base) {
1121
+ if (!base) throw new Error('Usage: node update-dependencies.mjs policy-check <ref>')
1122
+
1123
+ const blocked = (await readPolicy('npm')).entries.map((entry) => entry.package)
1124
+ const atBase = (file) => {
1125
+ try {
1126
+ return JSON.parse(capture('git', ['show', `${base}:${file}`]))
1127
+ } catch {
1128
+ return null
1129
+ }
1130
+ }
1131
+ const now = (file) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null)
1132
+
1133
+ const problems = policyViolations({
1134
+ blocked,
1135
+ beforeManifest: atBase('package.json'),
1136
+ afterManifest: now('package.json'),
1137
+ beforeLock: atBase('package-lock.json'),
1138
+ afterLock: now('package-lock.json'),
1139
+ })
1140
+
1141
+ for (const problem of problems) console.error(problem)
1142
+ if (0 < problems.length) throw new Error('The change updates a package that the dependency policy holds back.')
1143
+
1144
+ log('No package of the dependency policy is updated.')
1145
+ }
1146
+
1147
+ /** Rewrite the ignore rules of .github/dependabot.yml from the policy. The workflow of the repository commits the result. */
1148
+ async function dependabotSync() {
1149
+ if (!existsSync(DEPENDABOT_FILE)) throw new Error(`${DEPENDABOT_FILE} does not exist.`)
1150
+
1151
+ const names = (await readPolicy('npm')).entries.map((entry) => entry.package)
1152
+ const text = readFileSync(DEPENDABOT_FILE, 'utf8')
1153
+ const synced = syncDependabot(text, names, 'npm')
1154
+
1155
+ if (null === synced) {
1156
+ throw new Error(
1157
+ `${DEPENDABOT_FILE} has no block "# BEGIN dependency-policy (npm)" ... "# END dependency-policy (npm)".`
1158
+ )
1159
+ }
1160
+
1161
+ if (synced === text) {
1162
+ log('The ignore rules of Dependabot are in sync with the policy.')
1163
+ return
1164
+ }
1165
+
1166
+ writeFileSync(DEPENDABOT_FILE, synced)
1167
+ log(`The ignore rules of Dependabot are updated: ${names.join(', ') || 'none'}.`)
1168
+ }
1169
+
1170
+ const modes = {
1171
+ update,
1172
+ release,
1173
+ tag,
1174
+ cascade,
1175
+ audit,
1176
+ policy: policyWatch,
1177
+ 'policy-validate': policyValidate,
1178
+ 'policy-check': policyCheck,
1179
+ 'dependabot-sync': dependabotSync,
1180
+ }
1167
1181
 
1168
- async function main(mode) {
1182
+ async function main(mode, argument) {
1169
1183
  if (!modes[mode]) {
1170
1184
  console.error(
1171
1185
  'Usage: node update-dependencies.mjs update | release | tag | cascade | audit | policy | policy-validate'
@@ -1175,7 +1189,7 @@ async function main(mode) {
1175
1189
  }
1176
1190
 
1177
1191
  try {
1178
- await modes[mode](loadConfig())
1192
+ await modes[mode](loadConfig(), argument)
1179
1193
  } catch (error) {
1180
1194
  console.error(secret(error.message))
1181
1195
  process.exitCode = 1
@@ -1183,5 +1197,5 @@ async function main(mode) {
1183
1197
  }
1184
1198
 
1185
1199
  if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
1186
- await main(process.argv[2])
1200
+ await main(process.argv[2], process.argv[3])
1187
1201
  }