@git.zone/cli 6.14.0 → 6.15.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.
@@ -0,0 +1,261 @@
1
+ import { inferVersionTypeFromPending } from "../helpers.changelog.js";
2
+ import {
3
+ calculateNewVersion,
4
+ type VersionType,
5
+ } from "../mod_commit/mod.helpers.js";
6
+
7
+ export type TReleaseVersionErrorCode =
8
+ | "malformed-version-floor"
9
+ | "unsupported-prerelease-floor"
10
+ | "noncanonical-version"
11
+ | "current-version-changed";
12
+
13
+ export class ReleaseVersionError extends Error {
14
+ constructor(
15
+ public readonly code: TReleaseVersionErrorCode,
16
+ messageArg: string,
17
+ ) {
18
+ super(messageArg);
19
+ this.name = "ReleaseVersionError";
20
+ }
21
+ }
22
+
23
+ /**
24
+ * `inert`: the current version already meets the floor, so it can be removed.
25
+ * `satisfied`: the inferred version already meets the floor.
26
+ * `applied`: the floor is higher than the inferred version and becomes the release version.
27
+ */
28
+ export type TReleaseVersionFloorOutcome = "inert" | "satisfied" | "applied";
29
+
30
+ export type TReleaseVersionLevelSource = "pending-changelog" | "flag";
31
+
32
+ export interface IReleaseVersionRequest {
33
+ currentVersion: string;
34
+ pendingChangelog: string;
35
+ /** A `--major`, `--minor` or `--patch` flag; the Pending changelog decides otherwise. */
36
+ levelOverride?: VersionType;
37
+ /** The raw `release.versionFloor` configuration value. */
38
+ versionFloor?: unknown;
39
+ }
40
+
41
+ export interface IReleaseVersionResolution {
42
+ currentVersion: string;
43
+ level: VersionType;
44
+ levelSource: TReleaseVersionLevelSource;
45
+ inferredVersion: string;
46
+ version: string;
47
+ versionFloor: { floor: string; outcome: TReleaseVersionFloorOutcome } | null;
48
+ /** The floor raised the major version above the inferred version, and Pending has no Breaking Changes section. */
49
+ floorRaisesMajorWithoutBreakingChanges: boolean;
50
+ }
51
+
52
+ /** Journaled only when the floor, not the changelog, decided the release version. */
53
+ export interface IReleaseVersionFloorRecord {
54
+ floor: string;
55
+ inferredVersion: string;
56
+ }
57
+
58
+ const canonicalVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
59
+ // The semver.org 2.0.0 grammar. It is consulted only after the canonical form
60
+ // failed, so a match here means prerelease or build metadata.
61
+ const decoratedSemverPattern =
62
+ /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
63
+
64
+ export const isCanonicalReleaseVersion = (valueArg: string): boolean =>
65
+ canonicalVersionPattern.test(valueArg);
66
+
67
+ const parseVersionCore = (valueArg: string): [bigint, bigint, bigint] => {
68
+ const match = canonicalVersionPattern.exec(valueArg);
69
+ if (!match) {
70
+ throw new ReleaseVersionError(
71
+ "noncanonical-version",
72
+ `Release versions must be canonical x.y.z semver, found ${JSON.stringify(valueArg)}.`,
73
+ );
74
+ }
75
+ return [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])];
76
+ };
77
+
78
+ /** Orders two canonical x.y.z versions: negative, zero or positive. */
79
+ export const compareReleaseVersions = (
80
+ leftArg: string,
81
+ rightArg: string,
82
+ ): number => {
83
+ const left = parseVersionCore(leftArg);
84
+ const right = parseVersionCore(rightArg);
85
+ for (let index = 0; index < left.length; index++) {
86
+ if (left[index] !== right[index])
87
+ return left[index] < right[index] ? -1 : 1;
88
+ }
89
+ return 0;
90
+ };
91
+
92
+ const majorOf = (versionArg: string): bigint => parseVersionCore(versionArg)[0];
93
+
94
+ // npm and the version bump arithmetic handle only safe integer components.
95
+ const hasSafeIntegerComponents = (versionArg: string): boolean =>
96
+ versionArg
97
+ .split(".")
98
+ .every((componentArg) => Number.isSafeInteger(Number(componentArg)));
99
+
100
+ /** Validates `release.versionFloor`; absent means no floor. */
101
+ export const parseReleaseVersionFloor = (
102
+ valueArg: unknown,
103
+ ): string | undefined => {
104
+ if (valueArg === undefined) return undefined;
105
+ if (typeof valueArg === "string" && isCanonicalReleaseVersion(valueArg)) {
106
+ if (hasSafeIntegerComponents(valueArg)) return valueArg;
107
+ throw new ReleaseVersionError(
108
+ "malformed-version-floor",
109
+ `release.versionFloor components must not exceed ${Number.MAX_SAFE_INTEGER}, found ${JSON.stringify(valueArg)}.`,
110
+ );
111
+ }
112
+ if (typeof valueArg === "string" && decoratedSemverPattern.test(valueArg)) {
113
+ throw new ReleaseVersionError(
114
+ "unsupported-prerelease-floor",
115
+ `release.versionFloor ${JSON.stringify(valueArg)} carries prerelease or build metadata; GitZone releases only canonical x.y.z versions.`,
116
+ );
117
+ }
118
+ throw new ReleaseVersionError(
119
+ "malformed-version-floor",
120
+ `release.versionFloor must be a canonical x.y.z semver string, found ${JSON.stringify(valueArg)}.`,
121
+ );
122
+ };
123
+
124
+ const decideFloorOutcome = (
125
+ currentVersionArg: string,
126
+ inferredVersionArg: string,
127
+ floorArg: string,
128
+ ): TReleaseVersionFloorOutcome => {
129
+ if (compareReleaseVersions(floorArg, currentVersionArg) <= 0) return "inert";
130
+ if (compareReleaseVersions(floorArg, inferredVersionArg) <= 0) {
131
+ return "satisfied";
132
+ }
133
+ return "applied";
134
+ };
135
+
136
+ /**
137
+ * The only place that decides the next release version: the level-inferred
138
+ * version, raised to `release.versionFloor` when the floor is higher.
139
+ */
140
+ export const resolveReleaseVersion = (
141
+ requestArg: IReleaseVersionRequest,
142
+ ): IReleaseVersionResolution => {
143
+ const pendingLevel = inferVersionTypeFromPending(requestArg.pendingChangelog);
144
+ const level = requestArg.levelOverride ?? pendingLevel;
145
+ const inferredVersion = calculateNewVersion(requestArg.currentVersion, level);
146
+ const levelSource: TReleaseVersionLevelSource = requestArg.levelOverride
147
+ ? "flag"
148
+ : "pending-changelog";
149
+ const unfloored = {
150
+ currentVersion: requestArg.currentVersion,
151
+ level,
152
+ levelSource,
153
+ inferredVersion,
154
+ };
155
+ const floor = parseReleaseVersionFloor(requestArg.versionFloor);
156
+ if (floor === undefined) {
157
+ return {
158
+ ...unfloored,
159
+ version: inferredVersion,
160
+ versionFloor: null,
161
+ floorRaisesMajorWithoutBreakingChanges: false,
162
+ };
163
+ }
164
+ if (!isCanonicalReleaseVersion(requestArg.currentVersion)) {
165
+ throw new ReleaseVersionError(
166
+ "noncanonical-version",
167
+ `release.versionFloor needs a canonical x.y.z current version to compare against, found ${JSON.stringify(requestArg.currentVersion)}.`,
168
+ );
169
+ }
170
+ const outcome = decideFloorOutcome(
171
+ requestArg.currentVersion,
172
+ inferredVersion,
173
+ floor,
174
+ );
175
+ const version = outcome === "applied" ? floor : inferredVersion;
176
+ return {
177
+ ...unfloored,
178
+ version,
179
+ versionFloor: { floor, outcome },
180
+ floorRaisesMajorWithoutBreakingChanges:
181
+ outcome === "applied" &&
182
+ majorOf(version) > majorOf(inferredVersion) &&
183
+ pendingLevel !== "major",
184
+ };
185
+ };
186
+
187
+ /**
188
+ * The version files must still hold the version the release was resolved
189
+ * from; otherwise the resolved version no longer follows from the checkout.
190
+ */
191
+ export const assertResolvedCurrentVersion = (
192
+ resolutionArg: IReleaseVersionResolution,
193
+ checkoutVersionArg: string,
194
+ ): void => {
195
+ if (checkoutVersionArg !== resolutionArg.currentVersion) {
196
+ throw new ReleaseVersionError(
197
+ "current-version-changed",
198
+ `The release checkout carries version ${checkoutVersionArg}, but v${resolutionArg.version} was resolved from ${resolutionArg.currentVersion}.`,
199
+ );
200
+ }
201
+ };
202
+
203
+ const createVersionFloorRecord = (
204
+ resolutionArg: IReleaseVersionResolution,
205
+ floorArg: string,
206
+ ): IReleaseVersionFloorRecord => ({
207
+ floor: floorArg,
208
+ inferredVersion: resolutionArg.inferredVersion,
209
+ });
210
+
211
+ export const toReleaseVersionFloorRecord = (
212
+ resolutionArg: IReleaseVersionResolution,
213
+ ): IReleaseVersionFloorRecord | undefined =>
214
+ resolutionArg.versionFloor?.outcome === "applied"
215
+ ? createVersionFloorRecord(resolutionArg, resolutionArg.versionFloor.floor)
216
+ : undefined;
217
+
218
+ /** Shared wording for the plan and the journal summary. */
219
+ export const describeAppliedVersionFloor = (
220
+ recordArg: IReleaseVersionFloorRecord,
221
+ versionArg: string,
222
+ ): string =>
223
+ `version floor: ${recordArg.floor} applied (inferred ${recordArg.inferredVersion} -> release ${versionArg})`;
224
+
225
+ const describeVersionFloor = (
226
+ resolutionArg: IReleaseVersionResolution,
227
+ ): string[] => {
228
+ const decision = resolutionArg.versionFloor;
229
+ if (!decision) return [];
230
+ switch (decision.outcome) {
231
+ case "inert":
232
+ return [
233
+ `version floor: ${decision.floor} inert (current ${resolutionArg.currentVersion} already meets it); remove release.versionFloor`,
234
+ ];
235
+ case "satisfied":
236
+ return [
237
+ `version floor: ${decision.floor} satisfied by inferred ${resolutionArg.inferredVersion}`,
238
+ ];
239
+ case "applied":
240
+ return [
241
+ describeAppliedVersionFloor(
242
+ createVersionFloorRecord(resolutionArg, decision.floor),
243
+ resolutionArg.version,
244
+ ),
245
+ ...(resolutionArg.floorRaisesMajorWithoutBreakingChanges
246
+ ? [
247
+ `version notice: the floor raises the major version above inferred ${resolutionArg.inferredVersion}, and Pending has no "### Breaking Changes" section`,
248
+ ]
249
+ : []),
250
+ ];
251
+ }
252
+ };
253
+
254
+ /** Plan lines that explain where the release version comes from. */
255
+ export const describeReleaseVersion = (
256
+ resolutionArg: IReleaseVersionResolution,
257
+ ): string[] => [
258
+ `version: ${resolutionArg.currentVersion} -> ${resolutionArg.version}`,
259
+ `version level: ${resolutionArg.level} (${resolutionArg.levelSource === "flag" ? `--${resolutionArg.level}` : "Pending changelog"})`,
260
+ ...describeVersionFloor(resolutionArg),
261
+ ];
@@ -4,7 +4,6 @@ import { logger } from "../gitzone.logging.js";
4
4
  import type { ICliMode } from "../helpers.climode.js";
5
5
  import { getCliMode, printJson } from "../helpers.climode.js";
6
6
  import {
7
- inferVersionTypeFromPending,
8
7
  movePendingToVersion,
9
8
  readPendingChangelog,
10
9
  } from "../helpers.changelog.js";
@@ -71,6 +70,15 @@ import {
71
70
  type ITsdockerReleaseClient,
72
71
  type IReleaseQualificationRequest,
73
72
  } from "./helpers.tsdockerprotocol.js";
73
+ import {
74
+ assertResolvedCurrentVersion,
75
+ describeAppliedVersionFloor,
76
+ describeReleaseVersion,
77
+ resolveReleaseVersion,
78
+ toReleaseVersionFloorRecord,
79
+ type IReleaseVersionFloorRecord,
80
+ type IReleaseVersionResolution,
81
+ } from "./helpers.releaseversion.js";
74
82
 
75
83
  export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
76
84
 
@@ -139,7 +147,23 @@ const runInternal = async (argvArg: any): Promise<void> => {
139
147
  workflow.giteaAssets,
140
148
  branchContext.pushUrl || "",
141
149
  );
142
- printReleasePlan(workflow, branchContext);
150
+ const pending = await readPendingChangelog(
151
+ plugins.path.join(branchContext.sourceCwd, workflow.changelogFile),
152
+ workflow.changelogPendingSection,
153
+ );
154
+ const projectType = await commitHelpers.detectProjectType(
155
+ branchContext.sourceCwd,
156
+ );
157
+ const versionResolution = resolveReleaseVersion({
158
+ currentVersion: await commitHelpers.readCurrentVersion(
159
+ projectType,
160
+ branchContext.sourceCwd,
161
+ ),
162
+ pendingChangelog: pending.block,
163
+ levelOverride: readReleaseLevelOverride(argvArg),
164
+ versionFloor: workflow.versionFloor,
165
+ });
166
+ printReleasePlan(workflow, branchContext, versionResolution);
143
167
  if (
144
168
  workflow.targets.includes("npm") &&
145
169
  workflow.npmPackageSource === "tspublish"
@@ -164,26 +188,11 @@ const runInternal = async (argvArg: any): Promise<void> => {
164
188
  preflightTsdocker,
165
189
  );
166
190
 
167
- const pending = await readPendingChangelog(
168
- plugins.path.join(branchContext.sourceCwd, workflow.changelogFile),
169
- workflow.changelogPendingSection,
170
- );
171
191
  if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
172
192
  throw new Error("No pending changelog entries. Nothing to release.");
173
193
  }
174
194
 
175
- const versionType = resolveVersionType(argvArg, pending.block);
176
- const projectType = await commitHelpers.detectProjectType(
177
- branchContext.sourceCwd,
178
- );
179
- const currentVersion = await commitHelpers.readCurrentVersion(
180
- projectType,
181
- branchContext.sourceCwd,
182
- );
183
- const plannedVersion = commitHelpers.calculateNewVersion(
184
- currentVersion,
185
- versionType,
186
- );
195
+ const newVersion = versionResolution.version;
187
196
  if (workflow.giteaAssets) {
188
197
  const { tokenEnv, manifestPath, ...destination } = workflow.giteaAssets;
189
198
  const token = process.env[tokenEnv];
@@ -193,7 +202,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
193
202
  );
194
203
  await new GiteaAssetsClient({
195
204
  destination,
196
- tag: `v${plannedVersion}`,
205
+ tag: `v${newVersion}`,
197
206
  commit: branchContext.sourceOid,
198
207
  token,
199
208
  }).preflight();
@@ -203,7 +212,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
203
212
  createDockerQualificationRequest(
204
213
  workflow,
205
214
  branchContext.sourceCwd,
206
- plannedVersion,
215
+ newVersion,
207
216
  branchContext.sourceOid,
208
217
  ),
209
218
  );
@@ -217,7 +226,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
217
226
  }
218
227
  const confirmed =
219
228
  await plugins.smartinteract.SmartInteract.getCliConfirmation(
220
- `Release v${plannedVersion} (${versionType}) now?`,
229
+ `Release v${newVersion} now?`,
221
230
  true,
222
231
  );
223
232
  if (!confirmed) {
@@ -226,7 +235,6 @@ const runInternal = async (argvArg: any): Promise<void> => {
226
235
  }
227
236
  }
228
237
 
229
- let newVersion = plannedVersion;
230
238
  branchContext = await prepareReleaseIntegration(
231
239
  smartshellInstance,
232
240
  branchContext,
@@ -255,7 +263,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
255
263
  expectedRemoteMainOid = integration.expectedRemoteMainOid;
256
264
  }
257
265
 
258
- newVersion = await runVersionStep(projectType, versionType, releaseCwd);
266
+ await runVersionStep(projectType, versionResolution, releaseCwd);
259
267
  await runChangelogStep(workflow, newVersion, releaseCwd);
260
268
  const releaseCommitOid = await runReleaseCommitStep(
261
269
  smartshellInstance,
@@ -327,6 +335,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
327
335
  releasePushUrl,
328
336
  expectedRemoteMainOid,
329
337
  version: newVersion,
338
+ versionFloor: toReleaseVersionFloorRecord(versionResolution),
330
339
  refs: releaseRefs,
331
340
  dockerRequest,
332
341
  tsdocker,
@@ -463,6 +472,7 @@ interface ICreateReleaseJournalOptions {
463
472
  releasePushUrl?: string;
464
473
  expectedRemoteMainOid?: string;
465
474
  version: string;
475
+ versionFloor?: IReleaseVersionFloorRecord;
466
476
  refs: IReleaseRefs;
467
477
  dockerRequest?: IReleaseQualificationRequest;
468
478
  tsdocker?: ITsdockerReleaseClient;
@@ -639,6 +649,9 @@ export const createReleaseJournal = async (
639
649
  tag: `v${optionsArg.version}`,
640
650
  mainOid: optionsArg.refs.mainOid,
641
651
  tagOid: optionsArg.refs.tagOid,
652
+ ...(optionsArg.versionFloor
653
+ ? { versionFloor: optionsArg.versionFloor }
654
+ : {}),
642
655
  },
643
656
  artifact,
644
657
  ...(packages.length || giteaAssets ? { packages } : {}),
@@ -890,6 +903,9 @@ const runReleaseRecover = async (
890
903
  const context = await withReleasePreparationRecovery(
891
904
  options,
892
905
  ensureUnpublished,
906
+ // The existing tag is authoritative: recovery never re-derives its version,
907
+ // and the failed run's level override that fed any floor decision is not
908
+ // recorded, so a recovered journal carries no version floor record.
893
909
  async (checkout, ensureCheckout) =>
894
910
  createReleaseJournal({
895
911
  pnpmCapability,
@@ -1168,6 +1184,14 @@ const assertResumeConfiguration = async (
1168
1184
  const printReleaseJournalSummary = (journalArg: TReleaseJournal): void => {
1169
1185
  console.log("");
1170
1186
  console.log(`Release v${journalArg.release.version}`);
1187
+ if (journalArg.release.versionFloor) {
1188
+ console.log(
1189
+ describeAppliedVersionFloor(
1190
+ journalArg.release.versionFloor,
1191
+ journalArg.release.version,
1192
+ ),
1193
+ );
1194
+ }
1171
1195
  console.log(`journal revision: ${journalArg.revision}`);
1172
1196
  console.log(
1173
1197
  `artifact: ${journalArg.artifact ? `${journalArg.artifact.integrity} (${journalArg.artifact.sha256})` : "none"}`,
@@ -1206,14 +1230,13 @@ const printReleaseJournalSummary = (journalArg: TReleaseJournal): void => {
1206
1230
  console.log("");
1207
1231
  };
1208
1232
 
1209
- function resolveVersionType(
1233
+ function readReleaseLevelOverride(
1210
1234
  argvArg: any,
1211
- pendingBlock: string,
1212
- ): commitHelpers.VersionType {
1235
+ ): commitHelpers.VersionType | undefined {
1213
1236
  if (argvArg.major) return "major";
1214
1237
  if (argvArg.minor) return "minor";
1215
1238
  if (argvArg.patch) return "patch";
1216
- return inferVersionTypeFromPending(pendingBlock);
1239
+ return undefined;
1217
1240
  }
1218
1241
 
1219
1242
  async function runCommandStep(
@@ -1252,27 +1275,28 @@ async function verifyCleanTree(
1252
1275
 
1253
1276
  async function runVersionStep(
1254
1277
  projectType: commitHelpers.ProjectType,
1255
- versionType: commitHelpers.VersionType,
1278
+ resolutionArg: IReleaseVersionResolution,
1256
1279
  cwdArg: string,
1257
- ): Promise<string> {
1280
+ ): Promise<void> {
1258
1281
  const currentVersion = await commitHelpers.readCurrentVersion(
1259
1282
  projectType,
1260
1283
  cwdArg,
1261
1284
  );
1262
- const newVersion = commitHelpers.calculateNewVersion(
1263
- currentVersion,
1264
- versionType,
1285
+ assertResolvedCurrentVersion(resolutionArg, currentVersion);
1286
+ logger.log(
1287
+ "info",
1288
+ `Bumping version: ${currentVersion} -> ${resolutionArg.version}`,
1265
1289
  );
1266
- logger.log("info", `Bumping version: ${currentVersion} -> ${newVersion}`);
1267
1290
 
1268
- const commitInfo = new plugins.commitinfo.CommitInfo(cwdArg, versionType);
1291
+ const commitInfo = new plugins.commitinfo.CommitInfo(cwdArg, {
1292
+ version: resolutionArg.version,
1293
+ });
1269
1294
  await commitInfo.writeIntoPotentialDirs();
1270
1295
  await commitHelpers.updateProjectVersionFiles(
1271
1296
  projectType,
1272
- newVersion,
1297
+ resolutionArg.version,
1273
1298
  cwdArg,
1274
1299
  );
1275
- return newVersion;
1276
1300
  }
1277
1301
 
1278
1302
  async function runChangelogStep(
@@ -1516,6 +1540,7 @@ function shellQuote(value: string): string {
1516
1540
  function printReleasePlan(
1517
1541
  workflow: IResolvedReleaseWorkflow,
1518
1542
  branchContextArg: IReleaseBranchContext,
1543
+ versionResolutionArg: IReleaseVersionResolution,
1519
1544
  ): void {
1520
1545
  console.log("");
1521
1546
  console.log("gitzone release - resolved workflow");
@@ -1534,6 +1559,9 @@ function printReleasePlan(
1534
1559
  console.log(
1535
1560
  `changelog: ${workflow.changelogFile}#${workflow.changelogPendingSection}`,
1536
1561
  );
1562
+ for (const line of describeReleaseVersion(versionResolutionArg)) {
1563
+ console.log(line);
1564
+ }
1537
1565
  if (workflow.targets.includes("npm")) {
1538
1566
  console.log(`npm package source: ${workflow.npmPackageSource}`);
1539
1567
  console.log(
@@ -1687,7 +1715,9 @@ export function showHelp(mode?: ICliMode): void {
1687
1715
  console.log(
1688
1716
  " --merge Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
1689
1717
  );
1690
- console.log(" --major|--minor|--patch Override inferred semver level");
1718
+ console.log(
1719
+ " --major|--minor|--patch Override inferred semver level; release.versionFloor still applies",
1720
+ );
1691
1721
  console.log(
1692
1722
  " --plan Show workflow without fetching or mutating refs, files, index, or worktrees",
1693
1723
  );