@git.zone/cli 8.3.2 → 8.5.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 (39) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +29 -0
  3. package/dist_ts/helpers.workflow.js +37 -2
  4. package/dist_ts/mod_config/index.js +45 -3
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +108 -13
  7. package/dist_ts/mod_release/helpers.giteaassets.d.ts +47 -1
  8. package/dist_ts/mod_release/helpers.giteaassets.js +236 -56
  9. package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
  10. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  11. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  12. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  13. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  14. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  15. package/dist_ts/mod_release/helpers.releasephase.d.ts +9 -0
  16. package/dist_ts/mod_release/helpers.releasephase.js +25 -0
  17. package/dist_ts/mod_release/helpers.releasepreparation.js +6 -3
  18. package/dist_ts/mod_release/helpers.releasepublication.d.ts +12 -1
  19. package/dist_ts/mod_release/helpers.releasepublication.js +235 -52
  20. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  21. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  22. package/dist_ts/mod_release/index.js +149 -44
  23. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +16 -0
  24. package/package.json +5 -5
  25. package/readme.md +224 -17
  26. package/ts/00_commitinfo_data.ts +1 -1
  27. package/ts/helpers.workflow.ts +87 -0
  28. package/ts/mod_config/index.ts +50 -1
  29. package/ts/mod_release/classes.releasejournal.ts +165 -14
  30. package/ts/mod_release/helpers.giteaassets.ts +319 -64
  31. package/ts/mod_release/helpers.npmartifact.ts +302 -22
  32. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  33. package/ts/mod_release/helpers.releaseline.ts +214 -0
  34. package/ts/mod_release/helpers.releasephase.ts +26 -0
  35. package/ts/mod_release/helpers.releasepreparation.ts +12 -3
  36. package/ts/mod_release/helpers.releasepublication.ts +425 -78
  37. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  38. package/ts/mod_release/index.ts +213 -32
  39. package/ts/mod_release/interfaces.giteaassets.ts +19 -0
@@ -0,0 +1,214 @@
1
+ import {
2
+ compareReleaseVersions,
3
+ isCanonicalReleaseVersion,
4
+ releaseVersionMajor,
5
+ } from "./helpers.releaseversion.js";
6
+
7
+ /** The branch every release publishes from unless a release line names another. */
8
+ export const mainReleaseBranch = "main";
9
+ /** The npm dist-tag a `main` release carries. */
10
+ export const latestDistTag = "latest";
11
+
12
+ /**
13
+ * A maintenance line: an older major released from its own branch under its
14
+ * own npm dist-tag, so that `latest` never moves. The block is committed on
15
+ * the maintenance branch itself, which makes that branch, and only that
16
+ * branch, a release source.
17
+ */
18
+ export interface IReleaseLine {
19
+ branch: string;
20
+ distTag: string;
21
+ }
22
+
23
+ const isPlainObject = (
24
+ valueArg: unknown,
25
+ ): valueArg is Record<string, unknown> =>
26
+ typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
27
+
28
+ /**
29
+ * A branch name `git check-ref-format --branch` accepts, restricted to a
30
+ * portable character set. `main` and `HEAD` are never maintenance lines.
31
+ */
32
+ export const isReleaseLineBranchName = (valueArg: unknown): boolean =>
33
+ typeof valueArg === "string" &&
34
+ valueArg.length <= 200 &&
35
+ /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(valueArg) &&
36
+ !valueArg.includes("..") &&
37
+ !valueArg.includes("//") &&
38
+ !valueArg.includes("/.") &&
39
+ !valueArg.endsWith("/") &&
40
+ !valueArg.endsWith(".") &&
41
+ !valueArg.endsWith(".lock") &&
42
+ !valueArg.split("/").some((segmentArg) => segmentArg.endsWith(".lock")) &&
43
+ valueArg !== mainReleaseBranch &&
44
+ valueArg !== "HEAD";
45
+
46
+ /**
47
+ * A dist-tag of lowercase letters and digits joined by single hyphens, which
48
+ * starts with a letter. npm refuses a tag that is a valid semver range; within
49
+ * this alphabet only a bare partial version such as `v4` or `x` is one, so
50
+ * those are refused as well. `latest` belongs to `main`.
51
+ */
52
+ export const isReleaseLineDistTag = (valueArg: unknown): boolean =>
53
+ typeof valueArg === "string" &&
54
+ valueArg.length <= 64 &&
55
+ /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(valueArg) &&
56
+ !/^v*(?:\d+|x)$/.test(valueArg) &&
57
+ valueArg !== latestDistTag;
58
+
59
+ /** Validates `release.line`; absent means the release runs from `main`. */
60
+ export const parseReleaseLine = (
61
+ valueArg: unknown,
62
+ contextArg = "release.line",
63
+ ): IReleaseLine | undefined => {
64
+ if (valueArg === undefined) return undefined;
65
+ if (!isPlainObject(valueArg)) {
66
+ throw new Error(
67
+ `${contextArg} must be an object with "branch" and "distTag".`,
68
+ );
69
+ }
70
+ const keys = Object.keys(valueArg);
71
+ if (
72
+ keys.length !== 2 ||
73
+ !keys.includes("branch") ||
74
+ !keys.includes("distTag")
75
+ ) {
76
+ throw new Error(
77
+ `${contextArg} must contain exactly "branch" and "distTag".`,
78
+ );
79
+ }
80
+ if (!isReleaseLineBranchName(valueArg.branch)) {
81
+ throw new Error(
82
+ `${contextArg}.branch must be a canonical Git branch name other than main, found ${JSON.stringify(valueArg.branch)}.`,
83
+ );
84
+ }
85
+ if (!isReleaseLineDistTag(valueArg.distTag)) {
86
+ throw new Error(
87
+ `${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)}.`,
88
+ );
89
+ }
90
+ return {
91
+ branch: valueArg.branch as string,
92
+ distTag: valueArg.distTag as string,
93
+ };
94
+ };
95
+
96
+ export const getReleaseBranch = (lineArg: IReleaseLine | undefined): string =>
97
+ lineArg ? lineArg.branch : mainReleaseBranch;
98
+
99
+ export const getReleaseDistTag = (lineArg: IReleaseLine | undefined): string =>
100
+ lineArg ? lineArg.distTag : latestDistTag;
101
+
102
+ export const isSameReleaseLine = (
103
+ leftArg: IReleaseLine | undefined,
104
+ rightArg: IReleaseLine | undefined,
105
+ ): boolean =>
106
+ leftArg?.branch === rightArg?.branch && leftArg?.distTag === rightArg?.distTag;
107
+
108
+ /**
109
+ * A maintenance line keeps its major: a breaking change belongs to `main`,
110
+ * and a version of another major would leave the line it is tagged with.
111
+ */
112
+ export const assertReleaseLineVersion = (
113
+ lineArg: IReleaseLine | undefined,
114
+ currentVersionArg: string,
115
+ versionArg: string,
116
+ ): void => {
117
+ if (!lineArg) return;
118
+ if (!isCanonicalReleaseVersion(currentVersionArg)) {
119
+ throw new Error(
120
+ `Release line ${lineArg.distTag} needs a canonical x.y.z current version, found ${JSON.stringify(currentVersionArg)}.`,
121
+ );
122
+ }
123
+ if (releaseVersionMajor(versionArg) !== releaseVersionMajor(currentVersionArg)) {
124
+ throw new Error(
125
+ `Release line ${lineArg.distTag} keeps major ${releaseVersionMajor(currentVersionArg)}, but the release resolved ${currentVersionArg} -> ${versionArg}. ` +
126
+ "A maintenance line never changes its major: remove the Breaking Changes section, --major or release.versionFloor that raised it.",
127
+ );
128
+ }
129
+ };
130
+
131
+ /** Where one package's dist-tags were read. */
132
+ export interface IDistTagSubject {
133
+ packageName: string;
134
+ registry: string;
135
+ version: string;
136
+ distTag: string;
137
+ }
138
+
139
+ const describeDistTagValue = (valueArg: unknown): string =>
140
+ valueArg === undefined ? "absent" : JSON.stringify(valueArg);
141
+
142
+ /**
143
+ * Decides whether publishing `version` under `distTag` is allowed by the
144
+ * registry's current dist-tags; `undefined` means the package does not exist
145
+ * there. Returns why not, or `undefined` when publication may proceed.
146
+ *
147
+ * - `main` (`latest`): a canonical `latest` above the version would move
148
+ * `latest` downwards, so it refuses.
149
+ * - A line: `latest` must already carry a higher major, so the line can never
150
+ * take `latest`, and the line's own tag must not be ahead of the version.
151
+ */
152
+ export const findDistTagPublicationRefusal = (
153
+ distTagsArg: Record<string, unknown> | undefined,
154
+ subjectArg: IDistTagSubject,
155
+ ): string | undefined => {
156
+ const { packageName, registry, version, distTag } = subjectArg;
157
+ const latest = distTagsArg?.[latestDistTag];
158
+ if (distTag === latestDistTag) {
159
+ if (
160
+ typeof latest === "string" &&
161
+ isCanonicalReleaseVersion(latest) &&
162
+ compareReleaseVersions(latest, version) > 0
163
+ ) {
164
+ return (
165
+ `${packageName} at ${registry}: the latest dist-tag points at ${latest}, above ${version}. ` +
166
+ `A main release never moves latest downwards. Release an older major from its maintenance branch with release.line (see "Maintenance lines" in the gitzone readme).`
167
+ );
168
+ }
169
+ return undefined;
170
+ }
171
+ if (
172
+ typeof latest !== "string" ||
173
+ !isCanonicalReleaseVersion(latest) ||
174
+ releaseVersionMajor(latest) <= releaseVersionMajor(version)
175
+ ) {
176
+ return (
177
+ `${packageName} at ${registry}: release line ${distTag} requires the latest dist-tag to carry a higher major than ${version}, but latest is ${describeDistTagValue(latest)}. ` +
178
+ `Publishing could make ${version} the latest version.`
179
+ );
180
+ }
181
+ const lineVersion = distTagsArg?.[distTag];
182
+ if (lineVersion === undefined) return undefined;
183
+ if (
184
+ typeof lineVersion === "string" &&
185
+ isCanonicalReleaseVersion(lineVersion) &&
186
+ compareReleaseVersions(lineVersion, version) <= 0
187
+ ) {
188
+ return undefined;
189
+ }
190
+ return (
191
+ `${packageName} at ${registry}: the ${distTag} dist-tag points at ${describeDistTagValue(lineVersion)}, which is not below ${version}. ` +
192
+ "Publishing would move the release line backwards."
193
+ );
194
+ };
195
+
196
+ /**
197
+ * gitzone never writes dist-tags. When a line release finds `latest` on its
198
+ * own version, it names the command that restores the version `latest`
199
+ * carried when the publication was claimed.
200
+ */
201
+ export const describeLatestMovedConflict = (
202
+ subjectArg: IDistTagSubject,
203
+ observedLatestArg: unknown,
204
+ previousLatestArg: string | undefined,
205
+ ): string => {
206
+ const { packageName, registry, version, distTag } = subjectArg;
207
+ const restore = previousLatestArg
208
+ ? `Restore it with \`pnpm dist-tag add ${packageName}@${previousLatestArg} latest --registry=${registry}\`.`
209
+ : `Restore it with \`pnpm dist-tag add ${packageName}@<the version latest carried before> latest --registry=${registry}\`; this release did not claim the publication, so it recorded no earlier value.`;
210
+ return (
211
+ `${packageName} at ${registry}: release line ${distTag} published ${version}, but the latest dist-tag is ${describeDistTagValue(observedLatestArg)}, no longer a higher major. ` +
212
+ `gitzone does not repair dist-tags. ${restore}`
213
+ );
214
+ };
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Phase lines carry the wall-clock time they were printed at, so the log of a
3
+ * release, foreground or detached, shows where its time went.
4
+ */
5
+ export const formatReleasePhase = (
6
+ messageArg: string,
7
+ atArg: Date = new Date(),
8
+ ): string => `[${atArg.toISOString()}] ${messageArg}`;
9
+
10
+ /** Prints one timestamped phase line, separated from the output before it. */
11
+ export const printReleasePhase = (messageArg: string): void => {
12
+ console.log(`\n${formatReleasePhase(messageArg)}`);
13
+ };
14
+
15
+ /** A duration for people: `850 ms`, `7.1 s`, `12 min 4 s`, `1 h 13 min`. */
16
+ export const formatReleaseDuration = (millisecondsArg: number): string => {
17
+ const milliseconds = Math.max(0, Math.round(millisecondsArg));
18
+ if (milliseconds < 1000) return `${milliseconds} ms`;
19
+ if (milliseconds < 60_000) return `${Math.round(milliseconds / 100) / 10} s`;
20
+ const totalSeconds = Math.round(milliseconds / 1000);
21
+ const hours = Math.floor(totalSeconds / 3600);
22
+ const minutes = Math.floor((totalSeconds % 3600) / 60);
23
+ const seconds = totalSeconds % 60;
24
+ if (hours > 0) return `${hours} h ${minutes} min`;
25
+ return `${minutes} min ${seconds} s`;
26
+ };
@@ -22,6 +22,10 @@ import {
22
22
  } from "./helpers.npmartifact.js";
23
23
  import { getReleaseNpmPublicationOrder } from "./helpers.npmpackages.js";
24
24
  import { formatCommandFailure } from "./helpers.commandfailure.js";
25
+ import {
26
+ formatReleaseDuration,
27
+ printReleasePhase,
28
+ } from "./helpers.releasephase.js";
25
29
  import {
26
30
  ReleaseGitRemoteError,
27
31
  runGitRemoteInspection,
@@ -443,8 +447,8 @@ export const withIsolatedReleaseCheckout = async <T>(
443
447
  };
444
448
  let added = false;
445
449
  try {
446
- console.log(
447
- `\nPreparing the release checkout of ${options.mainOid} at ${checkout}`,
450
+ printReleasePhase(
451
+ `Preparing the release checkout of ${options.mainOid} at ${checkout}`,
448
452
  );
449
453
  await releaseGit(
450
454
  options.smartshell,
@@ -562,7 +566,8 @@ const run = async (
562
566
  command: string,
563
567
  phase: string,
564
568
  ) => {
565
- console.log(`\nRunning the release ${phase} in the release checkout`);
569
+ printReleasePhase(`Running the release ${phase} in the release checkout`);
570
+ const startedAt = Date.now();
566
571
  const result = await smartshell.exec(command, { cwd });
567
572
  if (result.exitCode !== 0)
568
573
  throw new Error(
@@ -572,4 +577,8 @@ const run = async (
572
577
  { command, output: "combined" },
573
578
  ),
574
579
  );
580
+ logger.log(
581
+ "success",
582
+ `Release ${phase} passed in the release checkout in ${formatReleaseDuration(Date.now() - startedAt)}.`,
583
+ );
575
584
  };