@git.zone/cli 8.8.2 → 8.9.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.
@@ -8,6 +8,7 @@ export type TReleaseVersionErrorCode =
8
8
  | "malformed-version-floor"
9
9
  | "unsupported-prerelease-floor"
10
10
  | "noncanonical-version"
11
+ | "invalid-prerelease-config"
11
12
  | "current-version-changed";
12
13
 
13
14
  export class ReleaseVersionError extends Error {
@@ -36,6 +37,24 @@ export interface IReleaseVersionRequest {
36
37
  levelOverride?: VersionType;
37
38
  /** The raw `release.versionFloor` configuration value. */
38
39
  versionFloor?: unknown;
40
+ prerelease?: IReleasePrerelease;
41
+ }
42
+
43
+ /** A committed main-branch publication channel; it never selects latest. */
44
+ export interface IReleasePrerelease {
45
+ identifier: string;
46
+ distTag: string;
47
+ }
48
+
49
+ /** The channel and its floor are immutable across interrupted releases. */
50
+ export interface IReleasePrereleaseRecord extends IReleasePrerelease {
51
+ versionFloor: string;
52
+ }
53
+
54
+ export interface IParsedPrereleaseVersion {
55
+ core: string;
56
+ identifier: string;
57
+ sequence: number;
39
58
  }
40
59
 
41
60
  export interface IReleaseVersionResolution {
@@ -47,6 +66,7 @@ export interface IReleaseVersionResolution {
47
66
  versionFloor: { floor: string; outcome: TReleaseVersionFloorOutcome } | null;
48
67
  /** The floor raised the major version above the inferred version, and Pending has no Breaking Changes section. */
49
68
  floorRaisesMajorWithoutBreakingChanges: boolean;
69
+ prerelease?: IReleasePrerelease;
50
70
  }
51
71
 
52
72
  /** Journaled only when the floor, not the changelog, decided the release version. */
@@ -56,6 +76,111 @@ export interface IReleaseVersionFloorRecord {
56
76
  }
57
77
 
58
78
  const canonicalVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
79
+ const prereleaseVersionPattern =
80
+ /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\.(0|[1-9]\d*)$/;
81
+
82
+ export const parsePrereleaseVersion = (
83
+ valueArg: string,
84
+ ): IParsedPrereleaseVersion | undefined => {
85
+ const match = prereleaseVersionPattern.exec(valueArg);
86
+ if (
87
+ !match ||
88
+ ![match[1], match[2], match[3], match[5]].every((componentArg) =>
89
+ Number.isSafeInteger(Number(componentArg)),
90
+ )
91
+ )
92
+ return undefined;
93
+ return {
94
+ core: `${match[1]}.${match[2]}.${match[3]}`,
95
+ identifier: match[4],
96
+ sequence: Number(match[5]),
97
+ };
98
+ };
99
+
100
+ export const isSupportedReleaseVersion = (valueArg: string): boolean =>
101
+ (isCanonicalReleaseVersion(valueArg) && hasSafeIntegerComponents(valueArg)) ||
102
+ parsePrereleaseVersion(valueArg) !== undefined;
103
+
104
+ export const releaseVersionCore = (valueArg: string): string =>
105
+ parsePrereleaseVersion(valueArg)?.core ?? valueArg;
106
+
107
+ /** Semver ordering for stable versions and the supported identifier.N form. */
108
+ export const compareSupportedReleaseVersions = (
109
+ leftArg: string,
110
+ rightArg: string,
111
+ ): number => {
112
+ const coreOrder = compareReleaseVersions(
113
+ releaseVersionCore(leftArg),
114
+ releaseVersionCore(rightArg),
115
+ );
116
+ if (coreOrder !== 0) return coreOrder;
117
+ const left = parsePrereleaseVersion(leftArg);
118
+ const right = parsePrereleaseVersion(rightArg);
119
+ if (!left && !right) return 0;
120
+ if (!left) return 1;
121
+ if (!right) return -1;
122
+ if (left.identifier !== right.identifier)
123
+ return left.identifier < right.identifier ? -1 : 1;
124
+ return Math.sign(left.sequence - right.sequence);
125
+ };
126
+
127
+ export const parseReleasePrerelease = (
128
+ valueArg: unknown,
129
+ contextArg = "release.prerelease",
130
+ ): IReleasePrerelease | undefined => {
131
+ if (valueArg === undefined) return undefined;
132
+ const fail = (): never => {
133
+ throw new ReleaseVersionError(
134
+ "invalid-prerelease-config",
135
+ `${contextArg} must contain exactly identifier and distTag: lowercase letters and digits joined by hyphens, starting with a letter; distTag must not be latest or a semver range.`,
136
+ );
137
+ };
138
+ if (
139
+ typeof valueArg !== "object" ||
140
+ valueArg === null ||
141
+ Array.isArray(valueArg)
142
+ )
143
+ return fail();
144
+ const config = valueArg as Record<string, unknown>;
145
+ if (
146
+ Object.keys(config).length !== 2 ||
147
+ typeof config.identifier !== "string" ||
148
+ typeof config.distTag !== "string"
149
+ )
150
+ return fail();
151
+ const identifierPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
152
+ if (
153
+ ![config.identifier, config.distTag].every(
154
+ (partArg) => partArg.length <= 64 && identifierPattern.test(partArg),
155
+ ) ||
156
+ config.distTag === "latest" ||
157
+ /^v*(?:\d+|x)$/.test(config.distTag)
158
+ )
159
+ return fail();
160
+ return { identifier: config.identifier, distTag: config.distTag };
161
+ };
162
+
163
+ export const toReleasePrereleaseRecord = (
164
+ prereleaseArg: IReleasePrerelease | undefined,
165
+ floorArg: string | undefined,
166
+ ): IReleasePrereleaseRecord | undefined => {
167
+ if (!prereleaseArg) return undefined;
168
+ const versionFloor = parseReleaseVersionFloor(floorArg, prereleaseArg);
169
+ if (!versionFloor)
170
+ throw new ReleaseVersionError(
171
+ "invalid-prerelease-config",
172
+ "release.prerelease requires a matching prerelease release.versionFloor.",
173
+ );
174
+ return { ...prereleaseArg, versionFloor };
175
+ };
176
+
177
+ export const isSameReleasePrerelease = (
178
+ leftArg: IReleasePrereleaseRecord | undefined,
179
+ rightArg: IReleasePrereleaseRecord | undefined,
180
+ ): boolean =>
181
+ leftArg?.identifier === rightArg?.identifier &&
182
+ leftArg?.distTag === rightArg?.distTag &&
183
+ leftArg?.versionFloor === rightArg?.versionFloor;
59
184
  // The semver.org 2.0.0 grammar. It is consulted only after the canonical form
60
185
  // failed, so a match here means prerelease or build metadata.
61
186
  const decoratedSemverPattern =
@@ -91,7 +216,7 @@ export const compareReleaseVersions = (
91
216
 
92
217
  /** The major component of a canonical x.y.z version. */
93
218
  export const releaseVersionMajor = (versionArg: string): bigint =>
94
- parseVersionCore(versionArg)[0];
219
+ parseVersionCore(releaseVersionCore(versionArg))[0];
95
220
 
96
221
  const majorOf = releaseVersionMajor;
97
222
 
@@ -104,7 +229,20 @@ const hasSafeIntegerComponents = (versionArg: string): boolean =>
104
229
  /** Validates `release.versionFloor`; absent means no floor. */
105
230
  export const parseReleaseVersionFloor = (
106
231
  valueArg: unknown,
232
+ prereleaseArg?: IReleasePrerelease,
107
233
  ): string | undefined => {
234
+ if (prereleaseArg) {
235
+ const parsed =
236
+ typeof valueArg === "string"
237
+ ? parsePrereleaseVersion(valueArg)
238
+ : undefined;
239
+ if (!parsed || parsed.identifier !== prereleaseArg.identifier)
240
+ throw new ReleaseVersionError(
241
+ "invalid-prerelease-config",
242
+ "release.prerelease requires release.versionFloor in the matching x.y.z-identifier.N form; keep this floor to make older CLIs fail closed.",
243
+ );
244
+ return valueArg as string;
245
+ }
108
246
  if (valueArg === undefined) return undefined;
109
247
  if (typeof valueArg === "string" && isCanonicalReleaseVersion(valueArg)) {
110
248
  if (hasSafeIntegerComponents(valueArg)) return valueArg;
@@ -137,6 +275,66 @@ const decideFloorOutcome = (
137
275
  return "applied";
138
276
  };
139
277
 
278
+ const resolvePrereleaseVersion = (
279
+ requestArg: IReleaseVersionRequest,
280
+ prereleaseArg: IReleasePrerelease,
281
+ floorArg: string,
282
+ pendingLevelArg: VersionType,
283
+ ): IReleaseVersionResolution => {
284
+ if (requestArg.levelOverride)
285
+ throw new ReleaseVersionError(
286
+ "invalid-prerelease-config",
287
+ "Prerelease numbering is controlled by release.versionFloor; --major, --minor and --patch are not allowed while release.prerelease is configured.",
288
+ );
289
+ const current = parsePrereleaseVersion(requestArg.currentVersion);
290
+ const floor = parsePrereleaseVersion(floorArg)!;
291
+ if (
292
+ !isSupportedReleaseVersion(requestArg.currentVersion) ||
293
+ (current && current.identifier !== prereleaseArg.identifier)
294
+ )
295
+ throw new ReleaseVersionError(
296
+ "noncanonical-version",
297
+ "The current version must be stable or belong to the configured prerelease identifier.",
298
+ );
299
+ const coreOrder = compareReleaseVersions(
300
+ floor.core,
301
+ releaseVersionCore(requestArg.currentVersion),
302
+ );
303
+ if (!current && coreOrder <= 0)
304
+ throw new ReleaseVersionError(
305
+ "invalid-prerelease-config",
306
+ "A prerelease floor must target a version above the current stable version.",
307
+ );
308
+ if (current && coreOrder < 0)
309
+ throw new ReleaseVersionError(
310
+ "invalid-prerelease-config",
311
+ "A prerelease floor cannot move its version core backwards.",
312
+ );
313
+ if (current?.sequence === Number.MAX_SAFE_INTEGER)
314
+ throw new ReleaseVersionError(
315
+ "invalid-prerelease-config",
316
+ "The prerelease sequence cannot exceed Number.MAX_SAFE_INTEGER.",
317
+ );
318
+ const inferredVersion = current
319
+ ? `${current.core}-${prereleaseArg.identifier}.${current.sequence + 1}`
320
+ : requestArg.currentVersion;
321
+ const applied =
322
+ compareSupportedReleaseVersions(floorArg, inferredVersion) > 0;
323
+ return {
324
+ currentVersion: requestArg.currentVersion,
325
+ level: pendingLevelArg,
326
+ levelSource: "pending-changelog",
327
+ inferredVersion,
328
+ version: applied ? floorArg : inferredVersion,
329
+ versionFloor: { floor: floorArg, outcome: applied ? "applied" : "inert" },
330
+ floorRaisesMajorWithoutBreakingChanges:
331
+ applied &&
332
+ majorOf(floorArg) > majorOf(inferredVersion) &&
333
+ pendingLevelArg !== "major",
334
+ prerelease: prereleaseArg,
335
+ };
336
+ };
337
+
140
338
  /**
141
339
  * The only place that decides the next release version: the level-inferred
142
340
  * version, raised to `release.versionFloor` when the floor is higher.
@@ -146,7 +344,25 @@ export const resolveReleaseVersion = (
146
344
  ): IReleaseVersionResolution => {
147
345
  const pendingLevel = inferVersionTypeFromPending(requestArg.pendingChangelog);
148
346
  const level = requestArg.levelOverride ?? pendingLevel;
149
- const inferredVersion = calculateNewVersion(requestArg.currentVersion, level);
347
+ const currentPrerelease = parsePrereleaseVersion(requestArg.currentVersion);
348
+ const prerelease = parseReleasePrerelease(requestArg.prerelease);
349
+ const floor = parseReleaseVersionFloor(requestArg.versionFloor, prerelease);
350
+ if (prerelease)
351
+ return resolvePrereleaseVersion(
352
+ requestArg,
353
+ prerelease,
354
+ floor!,
355
+ pendingLevel,
356
+ );
357
+ // Removing both channel settings explicitly promotes the exact prerelease core.
358
+ const inferredVersion = currentPrerelease
359
+ ? currentPrerelease.core
360
+ : calculateNewVersion(requestArg.currentVersion, level);
361
+ if (currentPrerelease && requestArg.levelOverride)
362
+ throw new ReleaseVersionError(
363
+ "invalid-prerelease-config",
364
+ "Promote a prerelease by removing release.prerelease and its floor, without a version-level flag.",
365
+ );
150
366
  const levelSource: TReleaseVersionLevelSource = requestArg.levelOverride
151
367
  ? "flag"
152
368
  : "pending-changelog";
@@ -156,7 +372,6 @@ export const resolveReleaseVersion = (
156
372
  levelSource,
157
373
  inferredVersion,
158
374
  };
159
- const floor = parseReleaseVersionFloor(requestArg.versionFloor);
160
375
  if (floor === undefined) {
161
376
  return {
162
377
  ...unfloored,
@@ -234,7 +449,13 @@ const describeVersionFloor = (
234
449
  switch (decision.outcome) {
235
450
  case "inert":
236
451
  return [
237
- `version floor: ${decision.floor} inert (current ${resolutionArg.currentVersion} already meets it); remove release.versionFloor`,
452
+ ...(resolutionArg.prerelease
453
+ ? [
454
+ `prerelease floor: ${decision.floor} retained (older CLIs refuse this channel)`,
455
+ ]
456
+ : [
457
+ `version floor: ${decision.floor} inert (current ${resolutionArg.currentVersion} already meets it); remove release.versionFloor`,
458
+ ]),
238
459
  ];
239
460
  case "satisfied":
240
461
  return [
@@ -78,7 +78,6 @@ import {
78
78
  import {
79
79
  assertReleaseLineVersion,
80
80
  findDistTagPublicationRefusal,
81
- getReleaseDistTag,
82
81
  getReleaseDockerAliasPolicy,
83
82
  isSameReleaseLine,
84
83
  latestDistTag,
@@ -114,6 +113,8 @@ import {
114
113
  } from "./helpers.tsdockerprotocol.js";
115
114
  import {
116
115
  assertResolvedCurrentVersion,
116
+ isSameReleasePrerelease,
117
+ toReleasePrereleaseRecord,
117
118
  describeAppliedVersionFloor,
118
119
  describeReleaseVersion,
119
120
  releaseVersionMajor,
@@ -239,6 +240,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
239
240
  pendingChangelog: pending.block,
240
241
  levelOverride: readReleaseLevelOverride(argvArg),
241
242
  versionFloor: workflow.versionFloor,
243
+ prerelease: workflow.prerelease,
242
244
  });
243
245
  assertReleaseLineVersion(
244
246
  workflow.line,
@@ -743,6 +745,14 @@ const recordReleaseIntent = async (
743
745
  ? { versionFloor: optionsArg.versionFloor }
744
746
  : {}),
745
747
  ...(optionsArg.workflow.line ? { line: optionsArg.workflow.line } : {}),
748
+ ...(optionsArg.workflow.prerelease
749
+ ? {
750
+ prerelease: toReleasePrereleaseRecord(
751
+ optionsArg.workflow.prerelease,
752
+ optionsArg.workflow.versionFloor,
753
+ ),
754
+ }
755
+ : {}),
746
756
  },
747
757
  plan: {
748
758
  targets: optionsArg.workflow.targets,
@@ -859,6 +869,15 @@ const prepareRecordedRelease = async (
859
869
  const { version } = intentArg.release;
860
870
  const workflow = await resolveReleaseWorkflow({ yes: true }, intentArg.plan);
861
871
  assertReleaseConfiguration(workflow, false);
872
+ if (
873
+ !isSameReleasePrerelease(
874
+ toReleasePrereleaseRecord(workflow.prerelease, workflow.versionFloor),
875
+ intentArg.release.prerelease,
876
+ )
877
+ )
878
+ throw new Error(
879
+ "Current release.prerelease or versionFloor does not match the recorded release.",
880
+ );
862
881
  if (!isSameReleaseLine(workflow.line, intentArg.release.line)) {
863
882
  throw new Error(
864
883
  `Current release.line (${describeReleaseLine(workflow.line)}) does not match the recorded release (${describeReleaseLine(intentArg.release.line)}).`,
@@ -1168,6 +1187,14 @@ export const createReleaseJournal = async (
1168
1187
  ...(optionsArg.workflow.line
1169
1188
  ? { line: optionsArg.workflow.line }
1170
1189
  : {}),
1190
+ ...(optionsArg.workflow.prerelease
1191
+ ? {
1192
+ prerelease: toReleasePrereleaseRecord(
1193
+ optionsArg.workflow.prerelease,
1194
+ optionsArg.workflow.versionFloor,
1195
+ ),
1196
+ }
1197
+ : {}),
1171
1198
  },
1172
1199
  artifact,
1173
1200
  ...(packages.length || giteaAssets ? { packages } : {}),
@@ -1188,7 +1215,7 @@ export const createReleaseJournal = async (
1188
1215
  access: optionsArg.workflow.targets.includes("npm")
1189
1216
  ? optionsArg.workflow.npmAccessLevel
1190
1217
  : "public",
1191
- tag: getReleaseDistTag(optionsArg.workflow.line),
1218
+ tag: optionsArg.workflow.npmDistTag,
1192
1219
  alreadyPublished: optionsArg.workflow.targets.includes("npm")
1193
1220
  ? optionsArg.workflow.npmAlreadyPublished
1194
1221
  : "success",
@@ -1394,6 +1421,10 @@ const runReleaseRecover = async (
1394
1421
  }
1395
1422
  const workflow = await resolveReleaseWorkflow({ yes: true });
1396
1423
  assertReleaseConfiguration(workflow, false);
1424
+ if (workflow.prerelease)
1425
+ throw new Error(
1426
+ "gitzone release recover does not support prereleases; continue the recorded intent with gitzone release resume <version> -y.",
1427
+ );
1397
1428
  if (workflow.line) {
1398
1429
  throw new Error(
1399
1430
  `gitzone release recover does not support release lines: a ${workflow.line.distTag} release records its intent, so continue it with \`gitzone release resume <version> -y\`.`,
@@ -1815,6 +1846,15 @@ const assertResumeConfiguration = async (
1815
1846
  journalArg: TReleaseJournal,
1816
1847
  cwdArg: string,
1817
1848
  ): Promise<void> => {
1849
+ if (
1850
+ !isSameReleasePrerelease(
1851
+ workflowArg.prerelease,
1852
+ journalArg.release.prerelease,
1853
+ )
1854
+ )
1855
+ throw new Error(
1856
+ "Current release.prerelease or versionFloor does not match the journal.",
1857
+ );
1818
1858
  if (!isSameReleaseLine(workflowArg.line, journalArg.release.line)) {
1819
1859
  throw new Error(
1820
1860
  `Current release.line (${describeReleaseLine(workflowArg.line)}) does not match the journal (${describeReleaseLine(journalArg.release.line)}).`,
@@ -1866,6 +1906,10 @@ const assertResumeConfiguration = async (
1866
1906
  const printReleaseJournalSummary = (journalArg: TReleaseJournal): void => {
1867
1907
  console.log("");
1868
1908
  console.log(`Release v${journalArg.release.version}`);
1909
+ if (journalArg.release.prerelease)
1910
+ console.log(
1911
+ `prerelease channel: ${journalArg.release.prerelease.identifier} -> npm dist-tag ${journalArg.release.prerelease.distTag} (latest is never moved)`,
1912
+ );
1869
1913
  if (journalArg.release.versionFloor) {
1870
1914
  console.log(
1871
1915
  describeAppliedVersionFloor(
@@ -2358,7 +2402,11 @@ const describeReleaseLineDistTags = async (
2358
2402
  workflowArg: IResolvedReleaseWorkflow,
2359
2403
  versionArg: string,
2360
2404
  ): Promise<string[]> => {
2361
- if (!workflowArg.line || !workflowArg.npmPackages) return [];
2405
+ if (
2406
+ (!workflowArg.line && !workflowArg.prerelease) ||
2407
+ !workflowArg.npmPackages
2408
+ )
2409
+ return [];
2362
2410
  const lines: string[] = [];
2363
2411
  for (const packageName of getReleaseNpmPublicationOrder(
2364
2412
  workflowArg.npmPackages,
@@ -2462,6 +2510,10 @@ async function printReleasePlan(
2462
2510
  console.log(`confirmation: ${workflow.confirmation}`);
2463
2511
  console.log(`plan: ${workflow.plan.join(" -> ")}`);
2464
2512
  console.log(`source branch: ${branchContextArg.sourceBranch}`);
2513
+ if (workflow.prerelease)
2514
+ console.log(
2515
+ `prerelease channel: ${workflow.prerelease.identifier} -> npm dist-tag ${workflow.prerelease.distTag} (latest is never moved)`,
2516
+ );
2465
2517
  if (workflow.line) {
2466
2518
  console.log(
2467
2519
  `release line: ${workflow.line.branch} -> npm dist-tag ${workflow.line.distTag} (major ${releaseVersionMajor(versionResolutionArg.currentVersion)}; latest is never moved)`,