@git.zone/cli 8.9.2 → 8.10.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.
@@ -46,6 +46,7 @@ import {
46
46
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
47
47
  import {
48
48
  getReleaseDockerAliasPolicy,
49
+ latestDistTag,
49
50
  parseReleaseLine,
50
51
  type IReleaseLine,
51
52
  } from "../mod_release/helpers.releaseline.js";
@@ -2162,11 +2163,15 @@ function validateReleaseLine(
2162
2163
  });
2163
2164
  return line;
2164
2165
  }
2166
+ const npmDistTag =
2167
+ line.distTag === latestDistTag
2168
+ ? "npm dist-tag latest while every higher major is a prerelease"
2169
+ : `npm dist-tag ${line.distTag}`;
2165
2170
  findings.push({
2166
2171
  level: "ok",
2167
2172
  message: isEnabled("docker")
2168
- ? `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}, and Docker images only under tags bound to the release version (tSDocker alias policy ${getReleaseDockerAliasPolicy(line)})`
2169
- : `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}`,
2173
+ ? `Release line ${line.branch} publishes under ${npmDistTag}, and Docker images only under tags bound to the release version (tSDocker alias policy ${getReleaseDockerAliasPolicy(line)})`
2174
+ : `Release line ${line.branch} publishes under ${npmDistTag}`,
2170
2175
  });
2171
2176
  return line;
2172
2177
  }
@@ -41,6 +41,7 @@ import {
41
41
  import {
42
42
  getReleaseDistTag,
43
43
  getReleaseDockerAliasPolicy,
44
+ latestDistTag,
44
45
  parseReleaseLine,
45
46
  type IReleaseLine,
46
47
  } from "./helpers.releaseline.js";
@@ -655,8 +656,9 @@ const assertReleaseLineRecord = (valueArg: unknown): IReleaseLine => {
655
656
 
656
657
  /**
657
658
  * Only a line release claims a publication with the `latest` version it found,
658
- * and the guard admitted it only with a higher major than the release. The
659
- * record exists once the publication was claimed.
659
+ * and the guard admitted it only with a higher major than the release. A line
660
+ * that takes `latest` itself records none. The record exists once the
661
+ * publication was claimed.
660
662
  */
661
663
  const assertPreviousLatest = (
662
664
  registryArg: Record<string, unknown>,
@@ -667,6 +669,7 @@ const assertPreviousLatest = (
667
669
  const prerelease = parsePrereleaseVersion(releaseArg.version);
668
670
  if (
669
671
  (!releaseArg.line && !releaseArg.prerelease) ||
672
+ releaseArg.line?.distTag === latestDistTag ||
670
673
  typeof previousLatest !== "string" ||
671
674
  !isCanonicalReleaseVersion(previousLatest) ||
672
675
  (prerelease
@@ -1259,11 +1259,11 @@ const tagSupersedesVersion = (
1259
1259
  /**
1260
1260
  * Reads the dist-tags of a published version. A prerelease needs stable latest
1261
1261
  * below its core and an exact or later sequence of its own channel and core.
1262
- * `latest` follows the rule
1263
- * above. A maintenance line's tag is superseded only by a later version of
1264
- * its own major, and a line release additionally requires `latest` to still
1265
- * carry a higher major: a line whose version took `latest` is a terminal
1266
- * conflict, because the registry now serves it as the newest release.
1262
+ * `latest`, of `main` or of a line that takes it, follows the rule above. A
1263
+ * maintenance line's own tag is superseded only by a later version of its
1264
+ * own major, and such a line additionally requires `latest` to still carry a
1265
+ * higher major: a line whose version took `latest` is a terminal conflict,
1266
+ * because the registry now serves it as the newest release.
1267
1267
  */
1268
1268
  export const assessPublishedDistTags = (
1269
1269
  distTagsArg: Record<string, unknown> | undefined,
@@ -1834,6 +1834,8 @@ export interface INpmDistTagPreflightOptions {
1834
1834
  packageNames: readonly string[];
1835
1835
  version: string;
1836
1836
  distTag: string;
1837
+ /** The release publishes from a release line. */
1838
+ line: boolean;
1837
1839
  /** What the operator runs once an authentication failure is fixed. */
1838
1840
  nextStep: string;
1839
1841
  probeOptions?: INpmArtifactProbeOptions;
@@ -1842,7 +1844,9 @@ export interface INpmDistTagPreflightOptions {
1842
1844
  /**
1843
1845
  * Before anything is committed or tagged, every package at every registry
1844
1846
  * must allow `version` under `distTag`: a `main` release never moves `latest`
1845
- * downwards, and a line never takes `latest` or moves its own tag backwards.
1847
+ * downwards, a line under its own tag never takes `latest` or moves its tag
1848
+ * backwards, and a line under `latest` takes it only while every higher major
1849
+ * is a prerelease.
1846
1850
  * A registry that cannot be read stops the release as well, because nothing
1847
1851
  * else proves the dist-tags it would change. A private read needs the
1848
1852
  * capability the release qualified with {@link assertPnpmDistTagReadCapability}.
@@ -1880,6 +1884,7 @@ export const assertNpmDistTagsAllowPublication = async (
1880
1884
  registry,
1881
1885
  version: optionsArg.version,
1882
1886
  distTag: optionsArg.distTag,
1887
+ line: optionsArg.line,
1883
1888
  },
1884
1889
  );
1885
1890
  if (refusal) refusals.push(refusal);
@@ -14,8 +14,10 @@ export const latestDistTag = "latest";
14
14
 
15
15
  /**
16
16
  * A maintenance line: an older major released from its own branch under its
17
- * own npm dist-tag, so that `latest` never moves. Its Docker images carry only
18
- * tags bound to the release version, so no floating image tag moves either.
17
+ * own npm dist-tag, so that `latest` never moves. A line whose dist-tag is
18
+ * `latest` takes it only while every higher major is a prerelease, see
19
+ * {@link findDistTagPublicationRefusal}. Its Docker images carry only tags
20
+ * bound to the release version, so no floating image tag moves either.
19
21
  * The block is committed on the maintenance branch itself, which makes that
20
22
  * branch, and only that branch, a release source.
21
23
  */
@@ -60,7 +62,10 @@ export const isReleaseLineDistTag = (valueArg: unknown): boolean =>
60
62
  !/^v*(?:\d+|x)$/.test(valueArg) &&
61
63
  valueArg !== latestDistTag;
62
64
 
63
- /** Validates `release.line`; absent means the release runs from `main`. */
65
+ /**
66
+ * Validates `release.line`; absent means the release runs from `main`. The
67
+ * dist-tag is a {@link isReleaseLineDistTag} tag of its own, or `latest`.
68
+ */
64
69
  export const parseReleaseLine = (
65
70
  valueArg: unknown,
66
71
  contextArg = "release.line",
@@ -86,9 +91,12 @@ export const parseReleaseLine = (
86
91
  `${contextArg}.branch must be a canonical Git branch name other than main, found ${JSON.stringify(valueArg.branch)}.`,
87
92
  );
88
93
  }
89
- if (!isReleaseLineDistTag(valueArg.distTag)) {
94
+ if (
95
+ valueArg.distTag !== latestDistTag &&
96
+ !isReleaseLineDistTag(valueArg.distTag)
97
+ ) {
90
98
  throw new Error(
91
- `${contextArg}.distTag must be lowercase letters and digits joined by hyphens, start with a letter, and be neither "latest" nor a semver range such as "v4", found ${JSON.stringify(valueArg.distTag)}.`,
99
+ `${contextArg}.distTag must be "latest" or lowercase letters and digits joined by hyphens that start with a letter and are not a semver range such as "v4", found ${JSON.stringify(valueArg.distTag)}.`,
92
100
  );
93
101
  }
94
102
  return {
@@ -158,6 +166,8 @@ export interface IDistTagSubject {
158
166
  registry: string;
159
167
  version: string;
160
168
  distTag: string;
169
+ /** The release publishes from a release line; required for a line that takes `latest`. */
170
+ line?: boolean;
161
171
  }
162
172
 
163
173
  const describeDistTagValue = (valueArg: unknown): string =>
@@ -170,8 +180,10 @@ const describeDistTagValue = (valueArg: unknown): string =>
170
180
  *
171
181
  * - `main` (`latest`): a canonical `latest` above the version would move
172
182
  * `latest` downwards, so it refuses.
173
- * - A line: `latest` must already carry a higher major, so the line can never
174
- * take `latest`, and the line's own tag must not be ahead of the version.
183
+ * - A line under its own tag: `latest` must already carry a higher major, so
184
+ * the line never takes `latest`, and the line's own tag must not be ahead
185
+ * of the version.
186
+ * - A line under `latest`: see {@link findLatestLineRefusal}.
175
187
  */
176
188
  export const findDistTagPublicationRefusal = (
177
189
  distTagsArg: Record<string, unknown> | undefined,
@@ -202,6 +214,7 @@ export const findDistTagPublicationRefusal = (
202
214
  return `${packageName} at ${registry}: prerelease dist-tag ${distTag} points at ${describeDistTagValue(tagged)}, which is not a prior release of the configured identifier; publishing would overwrite a different channel or move it backwards.`;
203
215
  }
204
216
  if (distTag === latestDistTag) {
217
+ if (subjectArg.line) return findLatestLineRefusal(distTagsArg, subjectArg);
205
218
  if (
206
219
  typeof latest === "string" &&
207
220
  isCanonicalReleaseVersion(latest) &&
@@ -239,6 +252,76 @@ export const findDistTagPublicationRefusal = (
239
252
  );
240
253
  };
241
254
 
255
+ /** The major of an npm version and whether it is a prerelease; `undefined` for anything else. */
256
+ const parseNpmVersion = (
257
+ valueArg: unknown,
258
+ ): { major: bigint; prerelease: boolean } | undefined => {
259
+ const match =
260
+ typeof valueArg === "string"
261
+ ? /^(0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(
262
+ valueArg,
263
+ )
264
+ : null;
265
+ return match
266
+ ? { major: BigInt(match[1]), prerelease: match[2] !== undefined }
267
+ : undefined;
268
+ };
269
+
270
+ /**
271
+ * A line whose dist-tag is `latest` releases the stable major while `main`
272
+ * has published the next major only as a prerelease. It may move `latest`
273
+ * only upwards within its own major, and only while the dist-tags show that
274
+ * the higher major is a prerelease: `latest` is a canonical version of the
275
+ * line's major not above the release, some dist-tag carries a prerelease of a
276
+ * higher major, and no dist-tag carries a stable version of a higher major.
277
+ * Once the higher major is stable the line needs a dist-tag of its own.
278
+ */
279
+ const findLatestLineRefusal = (
280
+ distTagsArg: Record<string, unknown> | undefined,
281
+ subjectArg: IDistTagSubject,
282
+ ): string | undefined => {
283
+ const { packageName, registry, version } = subjectArg;
284
+ const major = releaseVersionMajor(version);
285
+ const latest = distTagsArg?.[latestDistTag];
286
+ const ownTag = `Give the line a dist-tag of its own in release.line.distTag (see "Maintenance lines" in the gitzone readme).`;
287
+ const higherMajor = (prereleaseArg: boolean) =>
288
+ Object.entries(distTagsArg ?? {}).filter(([, valueArg]) => {
289
+ const parsed = parseNpmVersion(valueArg);
290
+ return (
291
+ parsed !== undefined &&
292
+ parsed.prerelease === prereleaseArg &&
293
+ parsed.major > major
294
+ );
295
+ });
296
+ const higherStable = higherMajor(false);
297
+ if (higherStable.length > 0) {
298
+ return (
299
+ `${packageName} at ${registry}: release line latest takes latest only while every higher major is a prerelease, but ${higherStable.map(([tagArg, valueArg]) => `${tagArg} carries ${describeDistTagValue(valueArg)}`).join(", ")}. ` +
300
+ ownTag
301
+ );
302
+ }
303
+ if (
304
+ typeof latest !== "string" ||
305
+ !isCanonicalReleaseVersion(latest) ||
306
+ releaseVersionMajor(latest) !== major
307
+ ) {
308
+ return (
309
+ `${packageName} at ${registry}: release line latest requires the latest dist-tag to carry a stable version of major ${major}, but latest is ${describeDistTagValue(latest)}. ` +
310
+ ownTag
311
+ );
312
+ }
313
+ if (compareReleaseVersions(latest, version) > 0) {
314
+ return `${packageName} at ${registry}: the latest dist-tag points at ${latest}, above ${version}. A release line never moves latest downwards.`;
315
+ }
316
+ if (higherMajor(true).length === 0) {
317
+ return (
318
+ `${packageName} at ${registry}: release line latest takes latest only while a higher major is published as a prerelease, but no dist-tag carries a prerelease above major ${major}. ` +
319
+ "Release this major from main instead."
320
+ );
321
+ }
322
+ return undefined;
323
+ };
324
+
242
325
  /**
243
326
  * gitzone never writes dist-tags. When a line release finds `latest` on its
244
327
  * own version, it names the command that restores the version `latest`
@@ -780,8 +780,8 @@ const markNpmProbeFailure = async (
780
780
  * Right before a version is published, the registry's dist-tags must still
781
781
  * allow it: the guard the release ran in preflight, repeated per package and
782
782
  * registry, because a registry can change between the two. A refusal is a
783
- * terminal dist-tag conflict and nothing is published. A line returns the
784
- * `latest` version it found, which its claim records.
783
+ * terminal dist-tag conflict and nothing is published. A line under its own
784
+ * tag returns the `latest` version it found, which its claim records.
785
785
  */
786
786
  const assertNpmDistTagsBeforePublication = async (
787
787
  optionsArg: IReleasePublicationOptions,
@@ -821,6 +821,7 @@ const assertNpmDistTagsBeforePublication = async (
821
821
  registry: selectorArg.registry,
822
822
  version: journalArg.release.version,
823
823
  distTag: journalArg.npm.tag,
824
+ line: journalArg.release.line !== undefined,
824
825
  });
825
826
  if (refusal) {
826
827
  await markUnclaimedTarget(
@@ -296,6 +296,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
296
296
  packageNames: getReleaseNpmPublicationOrder(workflow.npmPackages),
297
297
  version: newVersion,
298
298
  distTag: workflow.npmDistTag,
299
+ line: workflow.line !== undefined,
299
300
  nextStep: "release again",
300
301
  });
301
302
  }
@@ -2443,11 +2444,21 @@ const describeReleaseLineDistTags = async (
2443
2444
  registry,
2444
2445
  version: versionArg,
2445
2446
  distTag: workflowArg.npmDistTag,
2447
+ line: workflowArg.line !== undefined,
2446
2448
  });
2447
2449
  if (refusal) {
2448
2450
  lines.push(`${prefix} refused: ${refusal}`);
2449
2451
  continue;
2450
2452
  }
2453
+ if (workflowArg.npmDistTag === latestDistTag) {
2454
+ const otherTags = Object.entries(distTags ?? {})
2455
+ .filter(([tagArg]) => tagArg !== latestDistTag)
2456
+ .map(([tagArg, valueArg]) => `${tagArg} ${String(valueArg)}`);
2457
+ lines.push(
2458
+ `${prefix} ${latestDistTag} ${String(distTags?.[latestDistTag])} -> ${versionArg}, ${otherTags.join(", ")} unchanged`,
2459
+ );
2460
+ continue;
2461
+ }
2451
2462
  const lineVersion = distTags?.[workflowArg.npmDistTag];
2452
2463
  lines.push(
2453
2464
  `${prefix} ${workflowArg.npmDistTag} ${typeof lineVersion === "string" ? lineVersion : "(new)"} -> ${versionArg}, ${latestDistTag} ${String(distTags?.[latestDistTag])} unchanged`,
@@ -2527,7 +2538,7 @@ async function printReleasePlan(
2527
2538
  );
2528
2539
  if (workflow.line) {
2529
2540
  console.log(
2530
- `release line: ${workflow.line.branch} -> npm dist-tag ${workflow.line.distTag} (major ${releaseVersionMajor(versionResolutionArg.currentVersion)}; latest is never moved)`,
2541
+ `release line: ${workflow.line.branch} -> npm dist-tag ${workflow.line.distTag} (major ${releaseVersionMajor(versionResolutionArg.currentVersion)}; ${workflow.line.distTag === latestDistTag ? "latest moves only while every higher major is a prerelease" : "latest is never moved"})`,
2531
2542
  );
2532
2543
  }
2533
2544
  if (branchContextArg.sourceBranch !== branchContextArg.releaseBranch) {